home *** CD-ROM | disk | FTP | other *** search
/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / DATABASE / DBOL110B.ZIP;1 / DBONLINE.DOC < prev    next >
Encoding:
Text File  |  1993-11-23  |  169.5 KB  |  6,865 lines
  1.                       ‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹     ‹‹‹      ‹‹
  2.                       flflflflflflflflflflflflflflflfl‹‹‹‹‹‹flflfl‹‹‹‹‹‹flfl∞∞
  3.                       €€€€€€€€€€€€€€fl       €fl       €€∞∞
  4.                       ‹‹‹‹‹‹‹‹‹‹‹‹‹ flflflflflflflflflflflflflflflflfl‹‹∞∞
  5.                       flflflflflflflflflflflfl‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹flfl∞∞
  6.                       €€€€€€€€€€fl     ‹       ‹€     €€∞∞
  7.                       ‹‹‹‹‹‹‹‹‹ flflflflfl€‹flflflflflfl€‹‹flflflflfl‹‹∞∞
  8.                       flflflflflflflfl‹‹‹‹‹‹flflfl‹‹‹‹‹flflflfl‹‹‹‹‹flfl∞∞
  9.                       €€€€€€fl     ‹€€€€   ‹€€€€€     €€∞∞
  10.                       ‹‹‹‹‹ flflflflfl€‹‹‹‹‹fl€€‹‹‹‹‹‹flflflflfl‹‹∞∞
  11.                       flflflfl‹‹‹‹‹‹flflflflflflflflflflflflflflflfl‹‹‹‹‹flfl∞∞
  12.                       €€fl     ‹€€€€€€€€€€€€€€€€€     €€∞∞
  13.                       ‹‹€€€€€€‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹€€€€€‹‹∞∞
  14.                        ∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
  15.  
  16.  
  17.                            dB Online version 1.1
  18.                            ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒ
  19.                            Administrator's Manual
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.                              Merlin Systems Inc.
  28.                            Ottawa, Ontario, Canada
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37. Copyright (c) 1993 Merlin Systems Inc.   All rights  reserved.   This software
  38. product and this manual are copyrighted and all  rights are reserved by Merlin
  39. Systems Inc.   No part of  the contents  of this manual  may be  reproduced or
  40. transmitted in any form or by any means without  the written permission of the
  41. publisher.
  42.  
  43. Merlin Systems  Inc.  does  not  assume  any  liability  arising  out  of  the
  44. application or  use of  any products  described herein.   Merlin  Systems Inc.
  45. further reserves the right  to make changes  in any products  described herein
  46. without notice.  This document is subject to change without notice.
  47.  
  48. dBASE III+ is a registered trademark of Borland International Inc.
  49. dBASE IV is a registered trademark of Borland International Inc.
  50. Clipper is a registered trademark of Computer Associates Inc.
  51. FoxPro and MS-DOS are registered trademarks of Microsoft Corporation.
  52. DigiBoard is a registered trademark of DigiBoard Corp.
  53. PCBoard in a trademark of Clark Development Company, Inc.
  54. All other trademarks and registered trademarks are the properties of their
  55. respective owners.
  56.  
  57. Document: dbonline.doc
  58. Revision Date: 11/22/93  rev. 1
  59.  
  60.  
  61. Merlin Systems Inc.
  62. P.O. Box 3043, Station C
  63. Ottawa, Ontario
  64. K1Y 4J3 Canada
  65.  
  66. Phone:         613-236-1138
  67. BBS & Fax:     613-236-1481
  68.  
  69. Internet:      support@merlin-systems.on.ca
  70. FidoNet:       support 1:163/509
  71. UUCP:          uunet!mersys!support
  72. MHS:           support @ merlin [cserve]
  73. Compuserve:    >MHS: support @ merlin
  74.                >INTERNET: support@merlin-systems.on.ca
  75.  
  76.  
  77.  
  78.  
  79.                      C    O   N    T    E    N    T    S
  80.  
  81.  
  82.            Introduction  ........................................ 1
  83.            Installation  ........................................ 2
  84.              Diskette Installation  ............................. 2
  85.  
  86.              Zip File Installation  ............................. 2
  87.              Installed Files  ................................... 3
  88.            Database Concepts  ................................... 4
  89.  
  90.              What is a database?  ............................... 4
  91.              Fields  ............................................ 4
  92.  
  93.              Records  ........................................... 4
  94.                    ................................
  95.              Tags                                  .............. 4
  96.              Indexes  ........................................... 5
  97.  
  98.            Compiling  ........................................... 6
  99.              Source Code Format (.PRG)  ......................... 6
  100.              Compile Syntax  .................................... 6
  101.  
  102.              Examples  .......................................... 8
  103.            Execution  ........................................... 9
  104.              File Format Compatibility  ......................... 9
  105.  
  106.              Operation Modes  ................................... 9
  107.            Communications  ..................................... 12
  108.              PORT Command Syntax  .............................. 12
  109.  
  110.            Language Reference  ................................. 14
  111.              Symbols and Conventions  .......................... 14
  112.  
  113.              Expressions  ...................................... 15
  114.              Database Commands  ................................ 17
  115.              Database Functions  ............................... 57
  116.  
  117.              BBS Information Functions  ........................ 89
  118.            Appendices  ......................................... 98
  119.              Appendix 1:  Errorlevels  ......................... 98
  120.  
  121.              Appendix 2:  Compiler Messages  .................. 101
  122.              Appendix 3:  Runtime Errors  ..................... 103
  123.              Appendix 4: Full Screen Entry Keys  .............. 105
  124.  
  125.  
  126.                                                                   Introduction
  127.  
  128.  
  129. dB Online is the  first database application specifically  designed for online
  130. environments.  It provides a complete programming language that enables you to
  131. access, display, edit, and append to database files.
  132.  
  133. dB Online accesses industry standard  .DBF files with a superset  of the dBASE
  134. III+  programming  language.    This  allows  you  to  use  existing  database
  135. applications, or  easily create  new ones.    There is  no need  to learn  new
  136. scripting languages.
  137.  
  138. dB Online operates in three communications modes:
  139.  
  140. In BBS Doorway Mode , dB Online operates with  most popular BBS's as a seamless
  141. door.  BBS and user information is passed to dB Online and is available to the
  142. developer through xBase type function calls.
  143.  
  144. In Local/LAN Mode , dB Online provides a  method for your local users to access
  145. the dB Online application.  This mode is also useful for testing and debugging
  146. your application.
  147.  
  148. In Stand Alone  Mode     , dB  Online operates  without a  BBS.   It will  wait for
  149. callers and make a connection before executing the application.  This provides
  150. an alternative method to supply database access in an online environment.
  151.  
  152. dB Online is multi-user compatible  and provides full file  and record locking
  153. capabilities.  dB  Online employs  locking methods  compatible to  your native
  154. database management  system.   dB Online  can  be run  concurrently with  your
  155. existing applications and access the same data files simultaneously.
  156.  
  157. While dB Online's strength is  it's ability to access database  files, it also
  158. provides a complete language to create any type of door for your BBS. 
  159.  
  160.  
  161. dB Online Licence Levels
  162.  
  163. There are three  current license  levels of  dB Online.   They  are Shareware,
  164. Registered, and Pro.  The difference in features is outlined below.
  165.  
  166.      1 The Shareware version of dB Online is available free of charge.  It
  167.        allows full access to the dB Online language with the following
  168.        exceptions:  Any database files greater than 50 records are not
  169.        supported.  Only one database may be open at a time.  The RUN (shell to
  170.        DOS) command is not supported.
  171.  
  172.      2 The Registered version of dB Online removes the 50 record limit and
  173.        allows the RUN command.  Only a single database may be open at a time.
  174.  
  175.      3 The Pro version allows up to 20 databases to be open at once.  These
  176.        database may be related providing a fully relational database
  177.        management system.  In addition  dB Online Procan operate in a Stand
  178.        Alone mode.  This allows dB Online to operate without a BBS providing
  179.        an inexepensive method of providing database access online.
  180.  
  181. The license level is determined by the DBONLINE.KEY file.Installation
  182. There are two  methods of installing  dB Online.   There is  installation from
  183. diskette (Pro Version only) or installation from a zip file.
  184.  
  185.  
  186.                                                                               1
  187.  
  188.  
  189.                                                                   Installation
  190.  
  191.  
  192.  
  193.  
  194. Diskette Installation
  195.  
  196. The dB Online diskette includes an installation program.   The steps to follow
  197. are:
  198.  
  199.   1. Insert the diskette into the drive you want to install from:
  200.  
  201.   2. Run the install program on the diskette by typing:
  202.  
  203.           a:install
  204.  
  205.   3. The install program will ask you for the directory to install dB Online.
  206.      It will also ask you the file format compatibility you wish to install.
  207.      You have a choice of one or more of the following:  dBASE III+, dBASE IV,
  208.      Clipper or FoxPro.
  209.  
  210.   4. Install will copy all necessary files into the specified directory.
  211.  
  212.   5. Please review the readme.txt file for any product revisions.
  213.  
  214.   6. Once installation is complete proceed to the COMPILING and EXECUTION
  215.      sections to create your first online database application.
  216.  
  217.  
  218. Zip File Installation
  219.  
  220.  
  221. If you received dB Online from a download you should install as follows:
  222.  
  223.   1. Create a directory for dB Online:
  224.  
  225.           md c:\dbonline
  226.  
  227.   2. Unzip the dbol???.zip file into this directory: (??? refers to the
  228.      version number of dB Online)
  229.  
  230.           pkunzip dbol???.zip c:\dbonline
  231.  
  232.   3. Copy the dbonline.key file into the dB Online directory.  (Registered
  233.      version only)
  234.  
  235.   4. Please review the readme.txt file for any product revisions.
  236.  
  237.   5. Once installation is complete proceed to the COMPILING and EXECUTION
  238.      sections to create your first online database application.
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.                                                                               2
  250.  
  251.  
  252. Installed Files
  253.  
  254. The following files should be in your dB Online directory after installation:
  255.  
  256.      COMPILE.EXE         Source .PRG compiler
  257.      DBOLFOX.EXE         dB Online executable for FoxPro compatibility
  258.      DBOL4.EXE           dB Online executable for dBASE IV compatibility
  259.      DBOL3.EXE           dB Online executable for dBASE III+ compatibility
  260.      DBOLCLIP.EXE        dB Online executable for Clipper compatibility.
  261.      DBONLINE.DOC        ASCII version of this document
  262.      README.TXT          Product revisions and documentation updates.
  263.      REGISTER.DOC        Product registration information.
  264.      DBONLINE.KEY        Key file to access Registered functions.
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.                                                                               3
  313.  
  314.  
  315.                                                              Database Concepts
  316.  
  317.  
  318.  
  319.  
  320. What is a database?
  321.  
  322.      A database is a organized  collection of related information or  data.  A
  323.      common example of  a database  is a  telephone book.   It  contains name,
  324.      phone numbers, and addresses of  thousands of people.  Each  entry in the
  325.      phone book corresponds to a record , and each piece  of information in the
  326.      record, such as  the name  or phone number,  corresponds to  a field .   A
  327.      group of records such as a telephone book becomes a database.
  328.  
  329.      dB Online  accesses the  industry  standard .DBF  database  files.   This
  330.      standard, known as the xBase standard, is presently  the most widely used
  331.      database standard.
  332.  
  333.  
  334. Fields
  335.  
  336.  
  337.      A field    is the most  basic piece of data  in a database file.   There are
  338.      four attributes that describe each field.  These are described below:
  339.  
  340.      1 NAME:  This refers to the name that will be used to identify the field.
  341.        A field name can have a maximum of 10 characters.  It must begin with
  342.        an alphabetical character and may consist of any combination of
  343.        alphanumeric or underscore characters.
  344.  
  345.      2 TYPE:  The type of the field determines what kind of information is
  346.        stored.  There are 5 types of fields in the xBase standard:  Character,
  347.        Date, Logical, Numeric, and Memo.  The first four are fixed length
  348.        fields and the Memo field is variable length.
  349.  
  350.      3 LENGTH:  This refers to the number of characters or digits that can be
  351.        stored in the field.  
  352.  
  353.      4 DECIMALS:  This only applies to Numeric fields.  It specified the
  354.        number of digits to follow the decimal place.
  355.  
  356.      Memo fields are stored in a separate file and entries are referenced from
  357.      a fixed field in the database file.  A memo entry can be 64000 characters
  358.      in length.
  359.  
  360. Records
  361.  
  362.  
  363.      A record      consists of  one instance  of every  field.  Each  record has  a
  364.      unique record number.  The record number  indicates the physical position
  365.      of the data  in the data  file.   Each record also  has a  deletion flag.
  366.      This deletion flag determines weather a record is  to be removed when the
  367.      file is packed.
  368.  
  369. Tags
  370.  
  371.  
  372.      A tag      determines the  order that  the records  in the  database file  are
  373.      presented.  The tag does not affect the physical ordering of the database
  374.  
  375.                                                                               4
  376.  
  377.  
  378.      but only  the order  in which  they are  accessed.   Tags are  created by
  379.      specifying an expression that the records are ordered  from.  The results
  380.      of this expression is stored in the index key.
  381.  
  382. Indexes
  383.  
  384.  
  385.      An index is a file containing the sorted index keys for one or more tags.
  386.      dB Online supports several  formats of index  files.  They  are specified
  387.      below by the index file extensions:
  388.  
  389.           .CDX      FoxPro
  390.           .MDX      dBASE IV
  391.           .NDX      dBASE III+
  392.           .NTX      Clipper
  393.  
  394.      The .CDX and .MDX formats allow  you to have multiple tags  in each index
  395.      file,  and  production  index   files.    Production  index   files  open
  396.      automatically when the associated database is opened.   The .NDX and .NTX
  397.      index formats allow only one tag per index file.
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.                                                                               5
  439.  
  440.  
  441.                                                                      Compiling
  442.  
  443.  
  444.  
  445.  
  446. Source Code Format (.PRG)
  447.  
  448.      The source code  for a  dB Online program  consists of  one or  more .PRG
  449.      files.  These are the  standard source files for  all xBase applications.
  450.      The dB Online source program is defined by a  main .PRG file and optional
  451.      procedure files.
  452.  
  453.      The main file is the file that will be executed  first once the source is
  454.      compiled.   Procedure files  are  specified using  the  SET PROCEDURE  TO
  455.      command.  These files must include only procedure  definitions.  The main
  456.      file and all its procedure  files are compiled into a  single source .DBX
  457.      file.
  458.  
  459.      The following code provides an example of the Source Code Format:
  460.  
  461.      FILE:  main.prg
  462.  
  463. * Beginning of main.prg
  464. SET PROCEDURE TO function.prg      && Includes procedure file function.prg
  465. ...
  466. RETURN                             && ends main program
  467.  
  468. PROCEDURE proc1                    && procedure definition with main program
  469. ...
  470. RETURN
  471.  
  472.      FILE:  function.prg
  473.  
  474. *  Beginning of function.prg
  475. PROCEDURE proc2                    && Procedure files only contain procedures
  476. ...
  477. RETURN
  478. PROCEDURE proc3
  479. ...
  480. PROCEDURE proc4                    && RETURN assumed before PROCEDURE
  481. ...
  482. RETURN
  483.  
  484.  
  485.  
  486. Compile Syntax
  487.  
  488.  
  489.      The command line syntax of the dB Online compiler is:
  490.  
  491.      COMPILE <source.prg>
  492.  
  493.      <source.prg> identifies the main file to be compiled.
  494.  
  495.      The dB Online  compiler will compile  the source  code of the  main file.
  496.      Any procedure files identified in the main file with the SET PROCEDURE TO
  497.      command will  also be  compiled.   The dB  Online compiler  will do  full
  498.      syntax checking for all dB Online commands.
  499.  
  500.  
  501.                                                                               6
  502.  
  503.  
  504.      Compile will output two types of messages during the compile.  
  505.  
  506.      1 Error messages indicate errors in the source code program.  Compile
  507.        will indicate the source line number and show where the error occurred
  508.        in the actual source code.
  509.  
  510.      2 Warning messages indicate code that is not applicable to an executable
  511.        version of an xBase program.  These include commands such as SET TALK,
  512.        SET SCOREBOARD, etc.
  513.  
  514.      If there are zero  error messages as a  result of the compile,  dB Online
  515.      will then link all procedure calls in the code.  Procedure definition are
  516.      compared with  procedure  calls  to ensure  that  the  correct number  of
  517.      parameters  are  being   passed  and  that   all  procedure   calls  have
  518.      corresponding procedure definitions.
  519.  
  520.      If there  are no  linking  errors then  a  compiled source  .DBX   file is
  521.      created.  This is the file to be used with the dbonline.exe executable.
  522.  
  523.      All compilation error and warning messages are listed in APPENDIX 2.
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.                                                                               7
  565.  
  566.  
  567. Examples
  568.  
  569.      Consider the following program: sample.prg
  570.  
  571. ** File:  sample.prg
  572. ? "Hello"
  573. Return
  574.  
  575.      The output from the compiler would be:
  576.  
  577. dB Online 1.10  Compile                Copyright (c) 1993  Merlin Systems Inc.
  578. ------------------------------------------------------------------------------
  579. COMPILING:  sample.prg
  580.  
  581. TOTAL ERRORS:   0    TOTAL WARNINGS:   0 
  582.  
  583. LINKING PROCEDURE CALLS
  584.  
  585. SUCCESS
  586.  
  587. WRITING FILE: sample.dbx
  588.  
  589.  
  590.      For the following program: sample2.prg
  591.  
  592. ** File: sample2.prg
  593. USE customer.dbf ALIAX clients
  594. LIST
  595. RETURN
  596.  
  597.      The output from the compiler would be:
  598.  
  599. dB Online 1.10  Compile                Copyright (c) 1993  Merlin Systems Inc.
  600. ------------------------------------------------------------------------------
  601. COMPILING:  sample2.prg
  602.  
  603.  *** ERROR: Syntax Error.   Line:     2
  604. USE customer.dbf ALIAX clients
  605.                  ^
  606.  
  607. TOTAL ERRORS:   1    TOTAL WARNINGS:   0 
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.                                                                               8
  628.  
  629.  
  630.                                                                      Execution
  631.  
  632.  
  633. dB Online operates with a number of database file formats, and three operating
  634. modes.  These options are explained in this section.
  635.  
  636.  
  637.  
  638. File Format Compatibility
  639.  
  640. dB Online  presently supports  4 common  file formats.   There  is a  separate
  641. dbonline.exe file  for  each format.    This information  is  outlined in  the
  642. following table:
  643.  
  644.  
  645.                File      Index      Memo       dB Online
  646.                Format    Format     Format     Executable
  647.                dBASE III+.NDX       .DBT       DBOL3.EXE
  648.                CLIPPER   .NTX       .DBT       DBOLCLIP.EXE
  649.  
  650.                dBASE IV  .MDX       .DBT       DBOL4.EXE
  651.                FoxPro    .CDX       .FPT       DBOLFOX.EXE
  652.  
  653.  
  654. When referring to the dB Online executable, this manual will use dbonline.exe.
  655. However one of the above executables must be  replaced for dbonline.exe on the
  656. command line.
  657.  
  658. Operation Modes
  659.  
  660.  
  661. There are three modes of operation  for dB Online:  BBS Doorway  Mode, Local /
  662. LAN Mode and  Stand Alone Mode.   The dB  Online calling conventions  for each
  663. mode area outlined below.
  664.  
  665. BBS Doorway Mode
  666.  
  667.  
  668. To operate in BBS Doorway Mode you will need to use your BBS software to setup
  669. dB Online as a door.  The BBS software will require you to create a batch file
  670. for the doorway.  Please refer to your BBS documentation for assistance.
  671.  
  672. dB Online's command line syntax for BBS Doorway Mode operation is as follows:
  673.  
  674.      dbonline <source.dbx> <bbs drop files> [PORT:xxxx:n,y]
  675.  
  676.      <source.dbx> is the path and filename of the compiled .PRG files
  677.  
  678.      <bbs drop files> can consist of any combination of the following.
  679.  
  680.           DOOR.SYS
  681.           PCBOARD.SYS
  682.           DORINFOx.DEF
  683.           CALLINFO.BBS
  684.           CHAIN.TXT
  685.           USERS.SYS
  686.           EXITINFO.BBS
  687.  
  688.  
  689.  
  690.                                                                               9
  691.  
  692.  
  693.      The BBS drop files    are  created by the BBS  whenever a door is  executed.
  694.      Consult your BBS documentation for the BBS drop  files created.  At least
  695.      one of  the  files in  italics  is required  as  they  provide COMM  port
  696.      information for dB Online.  USERS.SYS and  EXITINFO.BBS only provide user
  697.      information.
  698.  
  699.      If the information in  the <bbs drop files>  provide a zero for  the COMM
  700.      port or  BAUD settings  then  operation will  default  to Local/Lan  Mode
  701.      operation.  This allows local nodes  to log into your BBS  and access the
  702.      dB Online door application.
  703.  
  704.      [PORT    :xxxx:n,y] is  for custom  port configuration   This  is not  usually
  705.      required for standard BBS Doorway Mode operation.   For more information,
  706.      see the Communications section.
  707.  
  708. Local/LAN Mode
  709.  
  710.  
  711. dB Online can be executed in Local or LAN Mode.  This allows for local testing
  712. and debugging of the application, as  well as servicing all LAN  nodes on your
  713. BBS.
  714.  
  715. dB Online's command line syntax for Local/Lan Mode operation is as follows:
  716.  
  717.      dbonline <source.dbx>
  718.  
  719.      <source.dbx> is the  path and  filename of  the compiled  .PRG file.   dB
  720.      Online assumes a .DBX file extension if none is given.
  721.  
  722.      Local/Lan Mode operation will not output  to any communications port.  It
  723.      only displays on the local screen.
  724.  
  725. Stand Alone Mode
  726.  
  727.  
  728. dB Online provides a method to operate over a COMM  port without the need of a
  729. BBS.  Stand  Alone mode  will wait  to receive a  call on  the modem  and then
  730. connect with the user before executing the .DBX file.
  731.  
  732. dB Online's command line syntax for Stand Alone Mode operation is as follows:
  733.  
  734.      dbonline <source.dbx> -SA PORT:xxxx:n,y
  735.  
  736.      <source.dbx> is the path and filename of the compiled .PRG file.
  737.  
  738.      The -SA option identifies Stand Alone Mode operation.
  739.  
  740.      The PORT  : command is  not optional in Stand Alone  operation.  It must be
  741.      specified in order that dB Online call detect incoming calls.  Please see
  742.      the Communications section for more details.
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.                                                                              10
  754.  
  755.  
  756.      Upon execution dB Online Stand Alone will enter  the call waiting screen.
  757.      This screen is shown below:
  758.  
  759.  UAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA?
  760.  3        UU  UUUUUUU       UUUUUUUU             UU                          3
  761.  3        UU  UUBBBBUU     UUBBBBBBUU            UU                          3
  762.  3        UU  UU    UU     UU      UU            UU  UU                      3
  763.  3        UU  UU    UU     UU      UU            UU                          3
  764.  3 UUUUUUUUU  UUUUUUU      UU      UU  UUUUUUUU  UU  UU  UUUUUUUU  UUUUUUUUU 3
  765.  3 UU     UU  UU    UU     UU      UU  UUB   UU  UU  UU  UUB   UU  UU     UU 3
  766.  3 UU     UU  UU    UU     UU      UU  UU    UU  UU  UU  UU    UU  UUUUUUUUU 3
  767.  3 UU     UU  UU    UU     UU      UU  UU    UU  UU  UU  UU    UU  UU        3
  768.  3 BUUUUUBUU  UUUUUUUB     BUUUUUUUUB  UU    UU  UU  UU  UU    UU  BUUUUUUUB 3
  769.  3                                                                           3
  770.  3         dB Online v1.10    Copyright (c) 1993 Merlin Systems Inc.         3
  771.  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAU
  772.  
  773.  U Port Status AAAAAAAAAAAAAAA?  U Connection Status AAAAAAAAAAAAAAAAAAAAAAAA?
  774.  3     Driver: COMx (UART)    3  3 t Resetting modem                         3
  775.  3       Port: 2              3  3 t Waiting for call                        3
  776.  3       Baud: 9600           3  3                                           3
  777.  3  Last Call: 10/21/93 09:24 3  3                                           3
  778.  3 # of Calls: 15             3  3                                           3
  779.  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAU  AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAU
  780.                     UAAAAAAAAAAAAA?    UAAAAAAAAAAAAAAAAAAA?
  781.                     3 <Esc>  Exit 3    3 <F2>  Local Login 3
  782.                     AAAAAAAAAAAAAAU    AAAAAAAAAAAAAAAAAAAAU
  783.  
  784.      This entry screen provides  information on the  PORT settings as  well as
  785.      previous caller  information.    There is  a  window  that indicates  the
  786.      Connection Status of the PORT.
  787.  
  788.      There are three events that will exit from the call waiting screen.
  789.  
  790.      1 A call is received.  dB Online will make a connection and then execute
  791.        the specified .DBX program.
  792.  
  793.      2 The local user presses <F2>.  dB Online will then execute the specified
  794.        .DBX program in local mode.
  795.  
  796.      3 The local user presses <Esc>.  dB Online will exit and return a DOS
  797.        errorlevel of 114 (defined in Appendix 1).
  798.  
  799.      Once dB Online terminates for any reason, it  will return control to DOS.
  800.      You must create  a batch file  that will re-enter  dB Online to  wait for
  801.      another caller.
  802.  
  803. Example:
  804.      This example batch file  will start dB  Online Stand Alone with  a source
  805.      file sample.dbx using  COMM port  1 at 9600  baud.   If the  user presses
  806.      <Esc> at the call waiting screen then the batch file will terminate.
  807.  
  808. :start
  809. dbonline sample.dbx -SA PORT:COM:1,9600
  810. REM if local user presses escape (error level 114) do not re-enter dB Online.
  811. if errorlevel 115 goto start
  812. if errorlevel 114 goto end
  813. goto start
  814. :end
  815.  
  816.                                                                              11
  817.  
  818.  
  819.                                                                 Communications
  820.  
  821.  
  822. dB Online  includes  the  ability  to  communicate  with  a  wide  variety  of
  823. communications hardware.  Support  is provided for standard  COM ports, FOSSIL
  824. drivers, Interrupt 14 (BIOS), DigiBoard, Arnet, and  Stargate smart I/O cards.
  825. 16550 FIFO support is automatically handled.
  826.  
  827. The PORT command line parameter is used to  specify custom port configurations
  828. for use with dB Online.  A PORT command is  required for Stand Alone operation
  829. and may be required for BBS Doorway Mode operation.
  830.  
  831.  
  832. PORT Command Syntax
  833.  
  834. The PORT command line parameter has the following syntax:
  835.  
  836.           PORT:<driver>:<port>,<baud>
  837.  
  838.      The <driver> settings are outlined below:
  839.  
  840.  
  841. COM
  842.  
  843.  
  844.      The COM <driver> setting is for standard COM ports.
  845.  
  846.      For ISA machines the <port> value  is between 1 and 4.   For Multichannel
  847.      machines the <port> value can be from 1 to 8.  
  848.  
  849.      The <baud> value can range up to 115200.
  850.  
  851. INT14
  852.  
  853.  
  854.      This INT14 <driver> setting is for Interrupt 14 (BIOS) ports.
  855.      With this driver, dB Online will access the serial port through Interrupt
  856.      14.  INT14 should be used if you have a TSR or driver that uses Int 14 to
  857.      route serial calls to something  other than the COM ports.   INT14 should
  858.      also be used if  you have a non-intelligent  I/O board and are  using its
  859.      driver software.
  860.  
  861.      The <port> value is the same as the standard COM port values.
  862.  
  863.      The <baud> value can range up to 19200.
  864.  
  865. FOSSIL
  866.  
  867.  
  868.      The FOSSIL <driver> setting is for FOSSIL drivers.
  869.  
  870.      Use this driver if you have a FOSSIL driver  installed.  Two such drivers
  871.      are X00 and BNU.
  872.  
  873.      The <port> and <baud> values are dependent on the FOSSIL driver.
  874.  
  875.  
  876.  
  877.  
  878.  
  879.                                                                              12
  880.  
  881.  
  882. SDIGI
  883.  
  884.      The SDIGI <driver> setting is for an Intelligent DigiBoard I/O board.
  885.  
  886.      A recent version  of the  DigiBoard    driver  will be  required.   The most
  887.      recent driver  as of  printing  of this  manual  was XDIDOS5.SYS  version
  888.      4.0.5.  It is available from the DigiBoard BBS at 612-943-0812.
  889.  
  890.      The <port> value  will be  the DigiBoard  channel to  be use.  The <baud>
  891.      value can range up to 115,200.
  892.  
  893.      For proper DigiBoard operation ensure the driver  is configured for EBIOS
  894.      support, and  that  the  IRQ line,  the  character  ready flag,  and  the
  895.      handshaking are all disabled.
  896.  
  897.  
  898. SARNET
  899.  
  900.      The SARNET <driver> setting is for an Intelligent Arnet I/O board.
  901.  
  902.      The <port> value is the channel  or handle as stated by  the Arnet device
  903.      driver upon loading.
  904.  
  905.      The <baud> value can range up to 115200.
  906.  
  907.  
  908. SSTAR
  909.  
  910.      The SSTAR <driver> setting is for an Intelligent StarGate I/O board.
  911.  
  912.      Your StarGate  smart I/O  card should  have an  I/O address  of 0x200  at
  913.      D000:0000 starting at COM5.
  914.  
  915.      The <port> value is  the handle or  channel to use  and can range  from 0
  916.      through to 32767.  
  917.  
  918.      The <baud> value can range up to 38400.
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.                                                                              13
  943.  
  944.  
  945.                                                             Language Reference
  946.  
  947.  
  948.  
  949.  
  950. Symbols and Conventions
  951.  
  952. The following symbols  are used throughout  the Language Reference  section to
  953. describe the syntax of the dB Online commands and functions.
  954.  
  955.  
  956.            Symbol          Definition
  957.            <item>          Angle brackets indicate that you must
  958.                            enter the enclosed item.  Do not enter
  959.                            the angled brackets.
  960.            [item]          Square brackets indicate that the
  961.                            enclosed item is optional.  Do not
  962.                            enter the Square brackets.
  963.  
  964.            <item1>|<item2> The vertical line separates choices of
  965.                            items.  Choose one of the options
  966.                            given.
  967.            <expr>          A valid dB Online expression must be
  968.                            entered.  See the Expressions section
  969.                            below.
  970.            <nexpr>         A numeric expression must be entered
  971.                            here.
  972.  
  973.            <cexpr>         A character expression must be entered
  974.                            here.
  975.            <dexpr>         A date expression must be entered here.
  976.  
  977.            <lexpr>         A logical expression must be entered
  978.                            here.
  979.            <var>           A memory variable identifier must be
  980.                            entered here.
  981.            <field>         A database field identifier must be
  982.                            entered here.
  983.  
  984.            <alais>         A character alias identifier must be
  985.                            entered here.
  986.            <proc name>     A procedure name must be entered here.
  987.            <filename>      A valid DOS filename must be entered
  988.                            here.  This can include the drive and
  989.                            full path if necessary.
  990.  
  991.            <text>          Any text may be entered here.
  992.            <scope>         Allows the specification of records.
  993.                            Valid values are:  ALL, RECORD <nexpr>,
  994.                            NEXT <nexpr>, REST.
  995.            <commands>      Any dB Online command may be entered
  996.                            here.
  997.  
  998.            <item list>     The word list following an item
  999.                            indicates that a number of items may be
  1000.                            entered.  These items must be separated
  1001.                            by a comma (,).
  1002.  
  1003.  
  1004.  
  1005.                                                                              14
  1006.  
  1007.  
  1008.            <item>          An item in italics indicate that it may
  1009.                            be macro substituted.  See the Macro
  1010.                            (&) function for more details.
  1011.  
  1012.  
  1013.  
  1014. The naming conventions for <var>,  <field>, <proc name>, and  <alias> area all
  1015. the same.    They  may be  up  to  10 characters  in  length,  can consist  of
  1016. alphanumeric and  underscore characters,  and  must begin  with an  alphabetic
  1017. character.
  1018.  
  1019. Expressions
  1020.  
  1021.  
  1022. dB Online provides a complete  expression evaluator.  The  components of these
  1023. expression are outlined below:
  1024.  
  1025. Variables/Fields
  1026.  
  1027.      Variables       can contain  4 types  of data:   character,  numeric, date  and
  1028.      logical.  Fields have the same data types and also include the memo field
  1029.      type.  
  1030.  
  1031. Aliases
  1032.  
  1033.      There are twenty work areas available in dB Online.  Aliases identify the
  1034.      work area of a  specific database.  The  alias of a work  area is usually
  1035.      the database file name  minus the extension.   This can be  changed using
  1036.      the USE...ALIAS command.   The alias for the  first 10 areas can  also be
  1037.      referred to as A through J.  
  1038.  
  1039.      To specify a field from  another work area the aliasing  indicator (-> or
  1040.      .) must be used.   For example  to specify the  NAME field in  the second
  1041.      work area you would type:
  1042.  
  1043.           B->NAME     or      B.NAME
  1044.  
  1045.      To avoid confusion between a memory variable and a field of the same name
  1046.      you may explicitly specify the variable by writing M->VARIABLE.
  1047.  
  1048. Mathematical Operators
  1049.  
  1050.      dB Online supports the standard symbols for mathematical calculations:
  1051.  
  1052.                          Operator Description
  1053.                              +    Addition
  1054.  
  1055.                              -    Subtraction
  1056.                              *    Multiplication
  1057.                              /    Division
  1058.  
  1059.                              ^    Exponent
  1060.                             **    Exponent
  1061.  
  1062.      These operators may all be used with numeric operands.
  1063.  
  1064.      The +,- operators may  be used with  character operands.  The  + operator
  1065.      will concatenate  two  character  strings.    The -  operator  will  also
  1066.  
  1067.  
  1068.                                                                              15
  1069.  
  1070.  
  1071.      concatenate two strings but will move any trailing  blanks from the first
  1072.      string to the end of the concatenated string.
  1073.  
  1074.      The +,- operators may be used  for date arithmetic.  Both can  be used to
  1075.      add or subtract a specific number of days from a date value.  For example
  1076.      {10/21/93} + 7  will return  10/28/93.  Two dates may  be subtracted from
  1077.      each other to determine the number of days in between them.
  1078.  
  1079. Relational Operators
  1080.  
  1081.      dB Online supports the following relational operators:
  1082.  
  1083.                          Operator Description
  1084.                              <    Less than
  1085.  
  1086.                              >    Greater than
  1087.                              =    Equal to
  1088.                             <>    Not equal to
  1089.  
  1090.                              #    Not equal to
  1091.                             <=    Less than or equal
  1092.                                   to
  1093.  
  1094.                             >=    Greater than or
  1095.                                   equal to
  1096.                              $    Is contained in
  1097.  
  1098.      The results of all relational operators is a logical value.
  1099.  
  1100.      The $  operator is  valid  with character  operands.   If  A  and B  area
  1101.      character strings, A$B returns True  (.T.) if A is either  identical to B
  1102.      or contained within B.
  1103.  
  1104. Logical Operators
  1105.  
  1106.      dB Online supports the following logical operators:
  1107.  
  1108.  
  1109.                          Operator Description
  1110.                            .AND.  Logical AND
  1111.                            .OR.   Logical OR
  1112.  
  1113.                            .NOT.  Logical NOT (unary
  1114.                                   operator)
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.  
  1131.                                                                              16
  1132.  
  1133.  
  1134. Operator Precedence
  1135.  
  1136.      dB Online  evaluates  expressions with  the  following standard  operator
  1137.      precedence:
  1138.  
  1139.                          OperatorsDescription
  1140.                             ( )   Parenthesis
  1141.                                   grouping
  1142.  
  1143.                            +   -  Unary positive and
  1144.                                   negative
  1145.                           **   ^  Exponent
  1146.                            *   /  Multiplication,
  1147.                                   Division
  1148.  
  1149.                            +   -  Addition,
  1150.                                   Subtraction
  1151.                          <   >    Relational
  1152.                           <=   >= Operators
  1153.                          =   !=   
  1154.                            #   $
  1155.  
  1156.                            .NOT.  Logical Not
  1157.                            .AND.  Logical And
  1158.                            .OR.   Logical Or
  1159.  
  1160.  
  1161.      All operations at the same  precedence level are performed  in order from
  1162.      left to right.
  1163.  
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.                                                                              17
  1195.  
  1196.  
  1197. Database Commands
  1198.  
  1199.      The following section outlines the available commands in  dB Online.  All
  1200.      coding examples in the next sections follow this format:
  1201.  
  1202. <command>                          && comments     Data Output
  1203.  
  1204.      The characters in the right most column are the output from the <command>
  1205.      given.
  1206.  
  1207.  
  1208. ?|??
  1209.  
  1210. Function:
  1211.      ?|?? evaluates and displays the value of one or more expressions.
  1212.  
  1213. Syntax:
  1214.      ?|?? <expr list>
  1215.  
  1216. Remarks:
  1217.      The single question mark  issues a carriage  return and line  feed before
  1218.      the expression list is displayed.   The double question  mark displays at
  1219.      the current cursor position.   The commas separating  the expression list
  1220.      output a single space in between expressions.   If an expression consists
  1221.      of a single MEMO  field identifier, then  dB Online will output  the memo
  1222.      contents word wrapped to the width set by SET MEMOWIDTH TO.
  1223.  
  1224. Example:
  1225. name = "John"
  1226. ? "Hello there",name                               Hello there John
  1227. ? "The date is "+ ctod(date())                     The date is 10/21/93
  1228. ? 5+3*6                                            23
  1229.  
  1230. See Also:
  1231.      @...SAY, TEXT...ENDTEXT, LIST, DISPLAY
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.                                                                              18
  1258.  
  1259.  
  1260. @...CLEAR
  1261.  
  1262. Function:
  1263.      @...CLEAR is used to clear a rectangular area on the screen.
  1264.  
  1265. Syntax:
  1266.      @ <nexpr1>,<nexpr2> CLEAR [TO <nexpr3>,<nexpr4>]
  1267.  
  1268. Remarks:
  1269.      dB Online will clear to the current background color the space defined by
  1270.      the 4  expressions.   The line  and row  given by  <nexpr1> and  <nexpr2>
  1271.      become the  top left  corner, and  <nexpr3>, <nexpr4>  become the  bottom
  1272.      right corner.   If the second  coordinates are  not given then  dB Online
  1273.      will clear to the bottom right corner of the display.
  1274.  
  1275. See Also:
  1276.      @...TO, CLEAR
  1277.  
  1278.  
  1279. @...SAY...GET
  1280.  
  1281. Function:
  1282.      @...SAY     ..GET       is  used to  create full  screen input  forms.   It disp
  1283.      information at specific coordinates.
  1284.  
  1285. Syntax:
  1286.      @ <nexpr1>,<nexpr2> [[SAY <expr> [PICTURE <cexpr>]]
  1287.           [GET <var>|<field> [PICTURE <cexpr>] [RANGE <expr1>,<expr2>]]]
  1288.  
  1289. Remarks:
  1290.      The output begins at the  row and column positions  specified by <nexpr1>
  1291.      and <nexpr2>.  For a 23*80  terminal the row coordinate can  range from 0
  1292.      to 22 and the column coordinate from 0 to 79.
  1293.  
  1294.      The @...SAY command  display information  that you do  not want  to edit.
  1295.      The value can be any valid dB Online expression.   The value of <expr> is
  1296.      evaluated and displayed at the row and column coordinates given.
  1297.  
  1298.      The @...GET command  displays and  allows editing  of data  from existing
  1299.      memory variables and  fields.  The  READ command activates  a full-screen
  1300.      editing mode which allows the editing of multiple GET fields.
  1301.  
  1302.      If an  @...SAY...GET  combination  command is  used,  a  single space  is
  1303.      entered between  the display  of the  SAY  expression and  the GET  input
  1304.      field.
  1305.  
  1306.      The RANGE        option is  used with  numeric  and date  variables to  specify
  1307.      acceptable lower <expr1> and <expr2> lower bounds for  input.  If data is
  1308.      entered outside the values specified by RANGE, dB  Online will not accept
  1309.      the input and request new data.
  1310.  
  1311.      The PICTURE  option  allows  formatting  of  the  output  expression  and
  1312.      restricts the type  of data  that may be  entered into  a variable.   The
  1313.      <cexpr>  is called a PICTURE clause and may  consist of a function   and/or
  1314.      a template.
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.                                                                              19
  1321.  
  1322.  
  1323.      If a PICTURE function is used,  the @ symbol must be  the first character
  1324.      in the clause.  If a PICTURE function is used  with a picture template, a
  1325.      space must separate the two.
  1326.  
  1327.      dB Online provides the following PICTURE functions:
  1328.  
  1329.              Symbol  Valid     Description
  1330.                      with type
  1331.                 C    NUMERIC   Display CR after a positive
  1332.                                number.  (SAY only)
  1333.  
  1334.                 X    NUMERIC   Display DB after a negative
  1335.                                number. (SAY only)
  1336.                 (    NUMERIC   Enclose negative number in
  1337.                                parentheses. (SAY only)
  1338.                 B    NUMERIC   Left justifies numeric data.
  1339.                                (SAY only)
  1340.  
  1341.                 Z    NUMERIC   Displays zero numeric value as a
  1342.                                blank string. (SAY only)
  1343.                 D    DATE           MM/DD/YY
  1344.                                Use {        } date format.
  1345.  
  1346.                 E    DATE           DD/MM/YY
  1347.                                Use {        } date format.
  1348.                 A    CHARACTER Allow only alphabetic characters.
  1349.                                (GET only)
  1350.                 !    CHARACTER Converts all letters to
  1351.                                uppercase.
  1352.  
  1353.                 R    CHARACTER Literal characters displayed in
  1354.                                template, but not entered in the
  1355.                                field.
  1356.                S<n>  CHARACTER Limits field width to <n>
  1357.                                characters.  GETs will scroll
  1358.                                horizontally to access whole
  1359.                                field.  <n> must be a literal
  1360.                                positive integer.
  1361.  
  1362.      A PICTURE template is created by using a single symbol for each character
  1363.      to be displayed  or input.   Any  character may  be used,  but characters
  1364.      other than the template symbols are considered literal characters.
  1365.  
  1366.      If the R  picture function is  used for  character input with  a template
  1367.      containing literal characters, the literals are inserted into the display
  1368.      and not  stored as  part of  the GET  variable.   If R  is not  used, the
  1369.      literals are displayed instead of the  corresponding string character and
  1370.      are stored in the GET variable.
  1371.  
  1372.      For numeric variables,  literal characters are  always inserted  into the
  1373.      display and not stored as part of the number.
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.                                                                              20
  1386.  
  1387.  
  1388.      dB Online provides the following template symbols:
  1389.  
  1390.                  Symbol Description
  1391.                    9    Allows digits for character and date
  1392.                         input.  Allows digits and signs for
  1393.                         numeric data.
  1394.  
  1395.                    #    Allows digits, blanks, and signs.
  1396.                    A    Allows only alphabetic characters.
  1397.                    L    Allows only logical characters:  t,
  1398.                         T, f, F, y, Y, n, N.
  1399.  
  1400.                    Y    Allows only logical characters:  y,
  1401.                         Y, n, N.
  1402.                    N    Allows alphanumeric characters.
  1403.  
  1404.                    X    Allows any character.
  1405.                    !    Converts letters to uppercase and
  1406.                         does not affect other characters
  1407.                    $    Displays dollar signs in place of
  1408.                         leading zeros for numeric data.
  1409.  
  1410.                    *    Displays asterisks in place of
  1411.                         leading zeros for numeric data.
  1412.                    .    Specifies the decimal position for
  1413.                         numeric data
  1414.                    ,    Displays if there are digits to the
  1415.                         left of the comma for numeric data.
  1416.  
  1417.  
  1418.      If a PICTURE template is used to GET a  decimal number, the decimal point
  1419.      must be included in the template.
  1420.  
  1421. Example:
  1422.      The following code provides examples of the @...SAY PICTURE command:
  1423.  
  1424. name = "John Smith"
  1425. @ 1,0 SAY name                     && Output name  John Smith
  1426. @ 2,0 SAY name PICTURE '@!'        && Convert to uppercase
  1427. JOHN SMITH
  1428. num1 = 456789
  1429. num2 = 23.78
  1430. num3 = -9.25
  1431. @ 3,0 SAY num1                                     456789
  1432. @ 4,0 SAY num1 PICTURE'$$$,$$$,$$$'                $$$$456,789
  1433. @ 5,0 SAY num2 PICTURE'***,***.***'                *****23,780
  1434. @ 6,0 SAY num3 PICTURE"@X *,***.**'                ****9.25 DB
  1435.  
  1436. See Also:
  1437.      ?|??, APPEND BLANK, CLEAR, CLEAR GETS, COL(), READ, ROW(),  SET BELL, SET
  1438.      CONFIRM, SET DELIMITERS, SET INTENSITY, TEXT...ENDTEXT
  1439.  
  1440. @...TO
  1441.  
  1442.  
  1443. Function:
  1444.      @...TO is used to draw a box with single or double lines.
  1445.  
  1446. Syntax:
  1447.  
  1448.                                                                              21
  1449.  
  1450.  
  1451.      @ <nexpr1>,<nexpr2> TO <nexpr3>,<nexpr4> [DOUBLE]
  1452.  
  1453. Remarks:
  1454.      The row and column  of the top  left corner of  the box are  specified by
  1455.      <nexpr1> and <nexpr2>.  The bottom right corner are specified by <nexpr3>
  1456.      and <nexpr4>.  If both row coordinates are the same, a horizontal line is
  1457.      drawn.  If the column coordinates are the same, a vertical line is drawn.
  1458.  
  1459.      The DOUBLE option draws a  double line box instead of  the default single
  1460.      line box.
  1461.  
  1462. See Also:
  1463.      @...CLEAR
  1464.  
  1465. ACCEPT
  1466.  
  1467.  
  1468. Function:
  1469.      ACCEPT allows character input into a memory variable.
  1470.  
  1471. Syntax:
  1472.      ACCEPT [<cexpr>] TO <var>
  1473.  
  1474. Remarks:
  1475.      ACCEPT displays  the  optional prompt  <cexpr>  before  waiting for  user
  1476.      input.  The character input is then placed into <var>.
  1477.  
  1478. Example:
  1479.      To input a users name:
  1480.  
  1481. ACCEPT "Please input your name :" TO name
  1482. ? name
  1483.  
  1484. See Also:
  1485.      @...SAY...GET, INPUT, WAIT
  1486.  
  1487. APPEND BLANK
  1488.  
  1489.  
  1490. Function:
  1491.      APPEND BLANK allows a  new record to  be added to  the end of  the active
  1492.      database file. 
  1493.  
  1494. Syntax:
  1495.      APPEND BLANK
  1496.  
  1497. Remarks:
  1498.      The new record is blank and  becomes the current record.   Any open index
  1499.      files are updated with the new record information.
  1500.  
  1501.      This command cannot be used with read only files.
  1502.  
  1503.  
  1504. AVERAGE
  1505.  
  1506. Function:
  1507.      AVERAGE calculates  the arithmetic  mean  of numeric  expressions in  the
  1508.      active database file.
  1509.  
  1510.  
  1511.                                                                              22
  1512.  
  1513.  
  1514. Syntax:
  1515.      AVERAGE [<scope>] <expr list> TO <var list> [WHILE <lexpr>] [FOR <lexpr>]
  1516.  
  1517. Remarks:
  1518.      All records in the current database are averaged  unless specified by the
  1519.      <scope>, WHILE, or FOR clauses.  The <expr list> items must correspond to
  1520.      the memory variables in <var list>.
  1521.  
  1522. Example:
  1523.      To AVERAGE the cost filed for all of John Smiths sales
  1524.  
  1525. USE sales
  1526. AVERAGE cost TO av_cost FOR salesman = "JS"
  1527. ? av_cost
  1528.  
  1529. See Also:
  1530.      COUNT, SUM
  1531.  
  1532. CANCEL
  1533.  
  1534.  
  1535. Function:
  1536.      CANCEL stops the execution of  the current dB Online session.   dB Online
  1537.      will close all files and return to the calling program (BBS etc.)
  1538.  
  1539. Syntax:
  1540.      CANCEL
  1541.  
  1542. Remarks:
  1543.      CANCEL will return a 0 to the DOS errorlevel.
  1544.  
  1545. See Also:
  1546.      QUIT, RETURN
  1547.  
  1548. CLEAR
  1549.  
  1550.  
  1551. Function:
  1552.      CLEAR erases  both the  local and  remote screens.   It  also clears  all
  1553. pending GET's.
  1554.  
  1555. Syntax:
  1556.      CLEAR
  1557.  
  1558. Remarks:
  1559.      The cursor is positioned at the top left hand  corner of the screen after
  1560. execution.
  1561.  
  1562. See Also:
  1563.      @...CLEAR, CLEAR GETS
  1564.  
  1565.  
  1566. CLEAR ALL
  1567.  
  1568. Function :
  1569.      CLEAR ALL closes all open database files, index file, and memo files, and
  1570. selects work area 1.
  1571.  
  1572. Syntax:
  1573.  
  1574.                                                                              23
  1575.  
  1576.  
  1577.      CLEAR ALL
  1578.  
  1579. Remarks:
  1580.      Memory variables are not cleared as in dBASE III+
  1581.  
  1582. See Also:
  1583.      CLOSE
  1584.  
  1585. CLEAR GETS
  1586.  
  1587.  
  1588. Function:
  1589.      CLEAR GETS releases all pending @...GET commands issued.
  1590.  
  1591. Syntax:
  1592.      CLEAR GETS
  1593.  
  1594. See Also:
  1595.      @...SAY...GET, CLEAR
  1596.  
  1597. CLEAR TYPEAHEAD
  1598.  
  1599.  
  1600. Function:
  1601.      CLEAR TYPEAHEAD empties the type-ahead buffer.
  1602.  
  1603. Syntax:
  1604.      CLEAR TYPEAHEAD
  1605.  
  1606. Remarks:
  1607.      CLEAR TYPEAHEAD will only clear characters that have been received by the
  1608.      local modem.  There can be significant delay in receiving characters from
  1609.      a remote  terminal  and  CLEAR TYPEAHEAD  will  not  clear characters  in
  1610.      transit.
  1611.  
  1612.  
  1613. CLOSE
  1614.  
  1615. Function:
  1616.      CLOSE is used to close various file types.
  1617.  
  1618. Syntax:
  1619.      CLOSE ALL|ALTERNATE|DATABASES|INDEX
  1620.  
  1621. Remarks:
  1622.      CLOSE ALTERNATE will close  the current alternate file.   CLOSE DATABASES
  1623.      will close all  database, index and  memo files  and select work  area 1.
  1624.      CLOSE INDEX will close all index  files in the current work  area.  CLOSE
  1625.      ALL will close all the above file types.
  1626.  
  1627. See Also:
  1628.      CLEAR ALL, RETURN, SET ALTERNATE TO, USE
  1629.  
  1630.  
  1631. CONTINUE
  1632.  
  1633. Function:
  1634.      CONTINUE searches for the next record in current database as specified by
  1635.      the conditions of the most recent LOCATE command.
  1636.  
  1637.                                                                              24
  1638.  
  1639.  
  1640.  
  1641. Syntax:
  1642.      CONTINUE
  1643.  
  1644. Remarks:
  1645.      See the LOCATE command for details
  1646.  
  1647. See Also:
  1648.      FOUND(), LOCATE, SEEK
  1649.  
  1650. COUNT
  1651.  
  1652.  
  1653. Function:
  1654.      COUNT calculates the number of records in the current database that match
  1655. specified conditions.
  1656.  
  1657. Syntax:
  1658.      COUNT [<scope>] [WHILE <lexpr>] [FOR <lexpr>] TO <var>
  1659.  
  1660. Remarks:
  1661.      All records in the current  database are counted unless  specified by the
  1662.      <scope>, WHILE, or FOR clauses.
  1663.  
  1664. Example:
  1665.      To count all your Ontario customers
  1666.  
  1667. USE customer
  1668. COUNT  FOR province = "ON" to number
  1669. ? number
  1670.  
  1671. See Also:
  1672.      AVERAGE, SUM
  1673.  
  1674. DELETE
  1675.  
  1676.  
  1677. Function:
  1678.      DELETE marks records in the current database for deletion.
  1679.  
  1680. Syntax:
  1681.      DELETE [<scope>] [WHILE <lexpr>] [FOR <lexpr>]
  1682.  
  1683. Remarks:
  1684.      Unless otherwise  specified  DELETE marks  only  the  current record  for
  1685.      deletion.
  1686.  
  1687.      DELETE cannot be used with read only files.
  1688.  
  1689. Example:
  1690. USE customer
  1691. ? DELETED()                                        .F.
  1692. DELETE
  1693. ? DELETED()                                        .T.
  1694.  
  1695. See Also:
  1696.      DELETED(), PACK, RECALL, SET DELETED
  1697.  
  1698.  
  1699.  
  1700.                                                                              25
  1701.  
  1702.  
  1703. DISPLAY
  1704.  
  1705. Function:
  1706.      DISPLAY is used to view the contents of the current database file.
  1707.  
  1708. Syntax:
  1709.      DISPLAY [OFF] [<scope>] [<expr list>] [WHILE <lexpr>] [FOR <lexpr>]
  1710.  
  1711. Remarks:
  1712.      The current  record  is displayed  unless  otherwise  specified with  the
  1713.      <scope>, WHILE, or FOR expressions.
  1714.  
  1715.      If <expr  list> is  not specified  then all  fields are  displayed.   The
  1716.      record number is  displayed unless the  OFF option  is included.   A memo
  1717.      field will be output  in a word wrapped  format only if it  is explicitly
  1718.      specified in <expr  list>.   The memo field  will be  output in  a column
  1719.      width defined by SET MEMOWIDTH TO.  
  1720.  
  1721. See Also:
  1722.      LIST, SET MEMOWIDTH
  1723.  
  1724.  
  1725. DO
  1726.  
  1727. Function:
  1728.      DO executes a user defined procedure and passes optional parameters.
  1729.  
  1730. Syntax:
  1731.      DO <proc name> [WITH <expr list>]
  1732.  
  1733. Remarks:
  1734.      The <proc name> is defined with the PROCEDURE command.  Program execution
  1735.      passes to  the  corresponding  procedure.    After  procedure  execution,
  1736.      program control passes to the command after the DO statement.
  1737.  
  1738.      The WITH  option  allows  parameter  passing  to  the  subroutine.    The
  1739.      parameter list  can contain  any valid  expression.   If  a parameter  is
  1740.      specified as a single memory variable,  any changes made to the variables
  1741.      value in  the  subroutine  will  be  reflected in  the  calling  programs
  1742.      variable.
  1743.  
  1744. Example:
  1745.      The following program calculates the area of a circle.
  1746.  
  1747. area = 0
  1748. DO areacalc WITH 2 , area
  1749. ? area                                             12.5663600
  1750.  
  1751. PROCEDURE areacalc 
  1752. PARAMETERS radius, result
  1753.   result = 3.14159 * radius^2
  1754. RETURN
  1755.  
  1756. See Also:
  1757.      PARAMETERS, PRIVATE, PROCEDURE, RETURN, SET PROCEDURE
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.                                                                              26
  1764.  
  1765.  
  1766. DO CASE
  1767.  
  1768. Function:
  1769.      DO CASE is a structured programming command  that chooses one alternative
  1770.      from a set of choices.
  1771.  
  1772. Syntax:
  1773.      DO CASE
  1774.           CASE <lexpr>
  1775.                <commands>
  1776.           [CASE <lexpr]
  1777.                <commands>
  1778.           [...]
  1779.           [OTHERWISE]
  1780.                <commands>
  1781.      ENDCASE
  1782.  
  1783. Remarks:
  1784.      The  <lexpr>  following  the  CASE  statements  determine  which  set  of
  1785.      <commands> are executed.   The <command>  set corresponding to  the first
  1786.      <lexpr> to evaluate to True (.T.) will be executed.   If none evaluate to
  1787.      True (.T.) then the  <commands> corresponding to the  OTHERWISE condition
  1788.      are executed if present.  After a set of <commands> are executed, program
  1789.      execution continues after the ENDCASE command.
  1790.  
  1791. See Also:
  1792.      DO, DO WHILE, IF, IIF()
  1793.  
  1794.  
  1795. DO WHILE
  1796.  
  1797. Function:
  1798.      DO WHILE  is  a  structured programming  command  that  allows a  set  of
  1799.      commands to be executed based on a specified condition.
  1800.  
  1801. Syntax:
  1802.           DO WHILE <lexpr>
  1803.                <commands>
  1804.                [EXIT]
  1805.                <commands>
  1806.                [LOOP]
  1807.                <commands>
  1808.           ENDDO
  1809.  
  1810. Remarks:
  1811.      The <lexpr>  following  the DO  WHILE  statement  determines whether  the
  1812.      <commands> in the structure are executed.  
  1813.  
  1814.      The EXIT command transfers  program control to the  command following the
  1815.      ENDDO statement.  It is often used with an IF...ENDIF structure.
  1816.  
  1817.      The  LOOP  command  transfers  program  control  back  to  the  DO  WHILE
  1818.      statement.    The  <lexpr>   is  then  reevaluated  and   the  <commands>
  1819.      conditionally executed.
  1820.  
  1821. Example:
  1822. USE customer
  1823. DO WHILE .NOT. EOF()
  1824.  
  1825.  
  1826.                                                                              27
  1827.  
  1828.  
  1829.   ....
  1830.   DISPLAY
  1831.   IF QUIT = .T.
  1832.     EXIT
  1833.   ENDIF
  1834. ENDDO
  1835.  
  1836. See Also:
  1837.      DO, DO CASE, IF, RETURN
  1838.  
  1839. ERASE
  1840.  
  1841.  
  1842. Function:
  1843.      ERASE deletes a file from the disk directory.
  1844.  
  1845. Syntax:
  1846.      ERASE <filename>    or
  1847.      DELETE FILE <filename>
  1848.  
  1849. Remarks:
  1850.      The file will be deleted if it exists on the drive.
  1851.  
  1852. Example:
  1853.      To delete c:\sales\customer.txt
  1854.  
  1855. file = "c:\sales\customer.txt"
  1856. ERASE &file
  1857.  
  1858. GO|GOTO
  1859.  
  1860.  
  1861. Function:
  1862.      GO|GOTO positions the record pointer  to a specific record  in the active
  1863.      database file.
  1864.  
  1865. Syntax:
  1866.      [GO|GOTO] <nexpr>  or
  1867.      GO|GOTO TOP|BOTTOM
  1868.  
  1869. Remarks:
  1870.      If the  [GO|GOTO] optional  command is  not specified  then <nexpr>  must
  1871.      begin with a numeric constant.
  1872.      If an index  file is  active GO TOP|BOTTOM  refer to  the top  and bottom
  1873.      logical records in the  index file.   GO|GOTO <nexpr> always refers  to a
  1874.      specific record number.   If SET DELETED is  ON, you may access  a record
  1875.      marked for deletion by directly specifying its record number.
  1876.  
  1877. Example:
  1878. USE customer
  1879. GO TOP
  1880. ? RECNO()                                          1
  1881. 5
  1882. ? RECNO()                                          5
  1883.  
  1884. See Also:
  1885.      RECNO(), SKIP
  1886.  
  1887.  
  1888.  
  1889.                                                                              28
  1890.  
  1891.  
  1892. IF
  1893.  
  1894. Function:
  1895.      IF is  a  structured  programming  command  that allows  the  conditional
  1896.      execution of commands.
  1897.  
  1898. Syntax:
  1899.      IF <lexpr>
  1900.           <commands>
  1901.      [ELSE]
  1902.           <commands>
  1903.      ENDIF
  1904.  
  1905. Remarks:
  1906.      If <lexpr> is evaluated  to True (.T.)  then the first set  of <commands>
  1907.      are executed and program  control is transferred to  the ENDIF statement.
  1908.      If <lexpr> is evaluated to  False (.F.) then dB  Online transfers program
  1909.      control to  the  ELSE  statement  or  the  ENDIF statement  if  the  ELSE
  1910.      statement is omitted.
  1911.  
  1912. See Also:
  1913.      DO CASE, IIF()
  1914.  
  1915.  
  1916. INPUT
  1917.  
  1918. Function:
  1919.      INPUT is used to input numeric information from the keyboard.
  1920.  
  1921. Syntax:
  1922.      INPUT [<cexpr>] TO <var>
  1923.  
  1924. Remarks:
  1925.      The optional  <cexpr> is  displayed as  a prompt  for input.   The  value
  1926.      returned to the <var> is the numeric value of the characters inputted.
  1927.  
  1928. Example:
  1929. INPUT "Type in your age " TO age   && If 28 is entered
  1930. ? age                                              28
  1931.  
  1932. See Also:
  1933.      ACCEPT, WAIT
  1934.  
  1935.  
  1936. LIST
  1937.  
  1938. Function:
  1939.      LIST is used to view the contents of the current database file.
  1940.  
  1941. Syntax:
  1942.      LIST [OFF] [<scope>] [<expr list>] [WHILE <lexpr>] [FOR <lexpr>]
  1943.  
  1944. Remarks:
  1945.      All records  are  listed unless  otherwise  specified  with the  <scope>,
  1946.      WHILE, or FOR expressions.
  1947.  
  1948.      If <expr  list> is  not specified  then all  fields are  displayed.   The
  1949.      record number is displayed unless the OFF option is included.  
  1950.  
  1951.  
  1952.                                                                              29
  1953.  
  1954.  
  1955.  
  1956.      A memo  field will  be output  in a  word wrapped  format only  if it  is
  1957.      explicitly specified in <expr list>.  The memo field  will be output in a
  1958.      column width defined by SET MEMOWIDTH TO.  
  1959.  
  1960. See Also:
  1961.      DISPLAY, SET MEMOWDTH
  1962.  
  1963. LOCATE
  1964.  
  1965.  
  1966. Function:
  1967.      LOCATE scans  the  active database  for  records  that satisfy  specified
  1968.      conditions.
  1969.  
  1970. Syntax:
  1971.      LOCATE [<scope>] [WHILE <lexpr>] [FOR <lexpr>]
  1972.  
  1973.      [CONTINUE]
  1974.  
  1975. Remarks:
  1976.      LOCATE searches the entire  database unless otherwise specified  with the
  1977.      <scope>, WHILE, or FOR expressions.
  1978.  
  1979.      LOCATE will find the first record to match  the specified conditions.  If
  1980.      this record is found then FOUND()  returns .T.  Use CONTINUE  to find the
  1981.      next occurrence of the specified conditions.
  1982.  
  1983.      When the record counter  reaches the end  of the file  or the end  of the
  1984.      <scope> then FOUND() returns .F.
  1985.  
  1986.      You can have a  different LOCATE/CONTINUE for  each work area.   The most
  1987.      recent LOCATE in any work area overrides any previous.
  1988.  
  1989. See Also:
  1990.      CONTINUE, FOUND(), SEEK
  1991.  
  1992. NOTE
  1993.  
  1994.  
  1995. Function:
  1996.      NOTE is used to indicate comments in the source code.
  1997.  
  1998. Syntax:
  1999.      NOTE|* <text>
  2000.      [<command>]&& <text>
  2001.  
  2002. Remarks:
  2003.      The <text> indicated above  is ignored by  the compiler.  If  any comment
  2004.      line ends  with a  semicolon, then  the next  line is  also treated  as a
  2005.      comment.
  2006.  
  2007.      && is used to insert a comment on the same line as a command.
  2008.  
  2009. Example:
  2010. USE customer.dbf                   && open customer database
  2011. NOTE  List all data
  2012. LIST
  2013.  
  2014.  
  2015.                                                                              30
  2016.  
  2017.  
  2018. ON ERROR
  2019.  
  2020. Function:
  2021.      ON ERROR is used to enable runtime error handling.
  2022.  
  2023. Syntax:
  2024.      ON ERROR [DO <proc name> [WITH <expr list>]]
  2025.  
  2026. Remarks:
  2027.      ON ERROR responds to dB Online database errors as outlined in APPENDIX 3.
  2028.      When a  runtime  error  occurs,  program  control will  transfer  to  the
  2029.      procedure <proc name> defined in the ON ERROR  command.  To disable error
  2030.      trapping enter ON ERROR <Enter> without a DO command.
  2031.  
  2032.      In the  procedure the  function  ERROR() will  identify  the error  which
  2033.      occurred and the  function MESSAGE() will  return a character  message of
  2034.      the error which occurred.
  2035.  
  2036.      If the  error recovery  procedure ends  with  a RETRY  command, the  same
  2037.      command which generated the error  will be executed.   However RETRY will
  2038.      not attempt to  re-execute any  conditional commands  such as  IF, WHILE,
  2039.      CASE etc.
  2040.  
  2041. Example:
  2042.      The following program will recover from the error:  File is already open.
  2043.  
  2044. ON ERROR DO recover
  2045. <commands>
  2046. USE customer
  2047. <commands>
  2048. RETURN
  2049.  
  2050. PROCEDURE recover
  2051.   IF ERROR() =  3
  2052.     CLOSE DATABASES
  2053.     RETRY                          && attempt to USE again
  2054.   ENDIF
  2055. RETURN
  2056.  
  2057. See Also:
  2058.      INKEY(), ON ESCAPE
  2059.  
  2060.  
  2061. ON ESCAPE
  2062.  
  2063. Function:
  2064.      ON ESCAPE responds to the user pressing E.
  2065.  
  2066. Syntax:
  2067.      ON ESCAPE [DO <proc name> [WITH <expr list>]]
  2068.  
  2069. Remarks:
  2070.      When the  user presses    <Esc>      during  program execution,  program control
  2071.      will be transferred to the procedure <proc name>  define in the ON ESCAPE
  2072.      DO command.   ON ESCAPE only  works when  SET ESCAPE is  ON.   To disable
  2073.      error trapping enter ON ESCAPE <Return> without a DO command.
  2074.  
  2075.  
  2076.  
  2077.  
  2078.                                                                              31
  2079.  
  2080.  
  2081.      During the execution of the  ON ESCAPE procedure, escape  key trapping is
  2082.      disabled.
  2083.  
  2084. Example:
  2085.      This example allows the user to cancel a long listing:
  2086.  
  2087. USE customer
  2088. SET ESCAPE ON
  2089. ON ESCAPE DO if_esc
  2090. LIST
  2091. RETURN
  2092.  
  2093. PROCEDURE if_esc
  2094. ACCEPT "Do you want to quit (Y/N)" TO response
  2095. IF 'Y' $ UPPER(response)
  2096.    RETURN
  2097. ELSE
  2098.    RETRY
  2099. ENDIF
  2100.  
  2101. See Also:
  2102.      INKEY(), ON ERROR, READKEY(), SET ESCAPE
  2103.  
  2104. PACK
  2105.  
  2106.  
  2107. Function:
  2108.      PACK permanently removes  all record  marked for  deletion in  the active
  2109.      database file.
  2110.  
  2111. Syntax:
  2112.      PACK
  2113.  
  2114. Remarks:
  2115.      All open index files  are automatically REINDEXed and  all memofiles area
  2116.      automatically compressed.
  2117.  
  2118.      PACK cannot be used with read only files.
  2119.  
  2120. See Also:
  2121.      DELETE, RECALL, REINDEX
  2122.  
  2123. PARAMETERS
  2124.  
  2125.  
  2126. Function:
  2127.      PARAMETERS assigns  local variable  names  to data  items  passed from  a
  2128.      calling program.
  2129.  
  2130. Syntax:
  2131.      PARAMETERS <var list>
  2132.  
  2133. Remarks:
  2134.      The PARAMETERS command must follow the PROCEDURE <proc name> command.
  2135.  
  2136.      The <var list> corresponds to  the <expr list> from  the calling program.
  2137.      All variables  identified in  the  PARAMETERS list  are  private to  that
  2138.      procedure.    When  the  procedure  ends,  the  PARAMETER  variables  are
  2139.      released.
  2140.  
  2141.                                                                              32
  2142.  
  2143.  
  2144.  
  2145. See Also:
  2146.      DO, PRIVATE, PROCEDURE , PUBLIC, SET PROCEDURE
  2147.  
  2148. PRIVATE
  2149.  
  2150.  
  2151. Function:
  2152.      PRIVATE creates new memory variables in a lower-level subroutine.
  2153.  
  2154. Syntax:
  2155.      PRIVATE <var list>
  2156.  
  2157. Remarks:
  2158.      Any changes  made  to  private  memory  variables  do  not  affect  other
  2159.      variables of the same name in higher level  procedures.  When a procedure
  2160.      containing a private  memory variable ends,  the value hidden  by PRIVATE
  2161.      variable are then available.  Any variables defined  in a PARAMETERS list
  2162.      are PRIVATE for that subroutine.
  2163.  
  2164. See Also:
  2165.      DO, PARAMETERS, PUBLIC
  2166.  
  2167. PROCEDURE
  2168.  
  2169.  
  2170. Function:
  2171.      PROCEDURE identifies the beginning of a procedure subroutine definition.
  2172.  
  2173. Syntax:
  2174.      PROCEDURE <proc name>
  2175.      [PARAMETERS <var list>]
  2176.      <commands>
  2177.  
  2178. Remarks:
  2179.      Procedures can be placed after the main program  or in separate procedure
  2180.      files.  These procedure files are identified in the main program with the
  2181.      SET PROCEDURE TO command.
  2182.      The optional PARAMETERS variable  list indicate PRIVATE  memory variables
  2183.      corresponding to the  parameters passed  with DO  <proc name>  WITH <expr
  2184.      list>.
  2185.  
  2186.      A RETURN  statement is  used to  terminate PROCEDURE  execution.   If the
  2187.      RETURN statement  is  not  included,  one  is  assumed  before  the  next
  2188.      PROCEDURE command or the end of file.
  2189.  
  2190. Example:
  2191.      The following program calculates the area of a circle.
  2192.  
  2193. area = 0
  2194. DO areacalc WITH 2 , area
  2195. ? area                                             12.5663600
  2196.  
  2197. PROCEDURE areacalc 
  2198.   PARAMETERS radius, result
  2199.   result = 3.14159 * radius^2
  2200. RETURN
  2201.  
  2202. See Also:
  2203.  
  2204.                                                                              33
  2205.  
  2206.  
  2207.      DO, PARAMETERS, SET PROCEDURE
  2208.  
  2209. PUBLIC
  2210.  
  2211.  
  2212. Function:
  2213.      PUBLIC makes memory variables globally available.
  2214. Syntax:
  2215.      PUBLIC <var list>
  2216.  
  2217. Remarks:
  2218.      All variables defined in  your program are considered  PUBLIC unless they
  2219.      are declared  as private  within  a subroutine  using  the PARAMETERS  or
  2220.      PRIVATE command.
  2221.  
  2222. See Also:
  2223.      PARAMETERS, PRIVATE
  2224.  
  2225. QUIT
  2226.  
  2227.  
  2228. Function:
  2229.      QUIT stops the  execution of the  current dB  Online session.   dB Online
  2230.      will close all files and return to the calling program (BBS etc.)
  2231.  
  2232. Syntax:
  2233.      QUIT
  2234.  
  2235. Remarks:
  2236.      QUIT will return a 0 to the DOS errorlevel.
  2237.  
  2238. See Also:
  2239.      CANCEL, RETURN
  2240.  
  2241.  
  2242. READ
  2243.  
  2244. Function:
  2245.      READ activates all @...GETs issued since the last CLEAR, CLEAR ALL, CLEAR
  2246.      GETS, or READ.
  2247.  
  2248. Syntax:
  2249.      READ [SAVE]
  2250.  
  2251. Remarks:
  2252.      READ allows the user to enter data into multiple fields on a single input
  2253.      screen.  The fields are defined by @...GET commands.  The user is allowed
  2254.      to tab through the input fields in order to  enter information.  The full
  2255.      screen editing keys are defined in APPENDIX 4.
  2256.  
  2257.      READ clears all GETs after editing is finished.  The SAVE option does not
  2258.      clear the GETs, they will be active when the next READ command is issued.
  2259.  
  2260.      If an @...GET is issued with  a field of a read only  file, then the read
  2261.      command will allow the user to browse through the data but not change any
  2262.      values.
  2263.  
  2264. Example:
  2265.  
  2266.  
  2267.                                                                              34
  2268.  
  2269.  
  2270.      To allow a user to enter  his name with a maximum of  12 characters.  The
  2271.      first character will be forced to uppercase.
  2272.  
  2273. name = SPACE(12)
  2274.  
  2275. @ 3,3 SAY "Enter your name: " GET name PICTURE "!XXXXXXXXXXX"
  2276. READ
  2277.  
  2278. See Also:
  2279.      @...SAY...GET, CLEAR, CLEAR GETS
  2280.  
  2281. RECALL
  2282.  
  2283.  
  2284. Function:
  2285.      RECALL unmarks records in the current database that  have been marked for
  2286. deletion.
  2287.  
  2288. Syntax:
  2289.      RECALL [<scope>] [WHILE <lexpr>] [FOR <lexpr>]
  2290.  
  2291. Remarks:
  2292.      Unless otherwise specified RECALL  unmarks only the current record.
  2293.      RECALL cannot be used with read only files.
  2294.  
  2295. Example:
  2296. USE customer
  2297. ? DELETED()                                        .T.
  2298. RECALL
  2299. ? DELETED()                                        .F.
  2300.  
  2301. See Also:
  2302.      DELETE, DELETED(), PACK, SET DELETED
  2303.  
  2304. REINDEX
  2305.  
  2306.  
  2307. Function:
  2308.      REINDEX rebuilds all active index files in the current work area.
  2309.  
  2310. Syntax:
  2311.      REINDEX
  2312.  
  2313. Remarks:
  2314.      Only index files  that have been  opened with the  corresponding database
  2315.      file will be rebuilt.
  2316.  
  2317.      REINDEX cannot be used with read only files.
  2318.  
  2319. See Also:
  2320.      PACK, SET INDEX, USE
  2321.  
  2322.  
  2323. RENAME
  2324.  
  2325. Function:
  2326.      RENAME changes the name of a file on disk.
  2327.  
  2328. Syntax:
  2329.  
  2330.                                                                              35
  2331.  
  2332.  
  2333.      RENAME <filename1> TO <filename2>
  2334.  
  2335. Remarks:
  2336.      If drive specifiers  are used,  they must both  indicate the  same drive.
  2337.      RENAME cannot be used to copy files to different drives.
  2338.  
  2339. REPLACE
  2340.  
  2341.  
  2342. Function:
  2343.      REPLACE changes the contents of specified fields in the current database.
  2344.  
  2345. Syntax:
  2346.      REPLACE [<scope>] <field> WITH <expr> [,<field> WITH <expr> ...]
  2347.           [WHILE <lexpr>] [FOR <lexpr>]
  2348.  
  2349. Remarks:
  2350.      REPLACE only changes the current record unless otherwise specified by the
  2351.      <scope>, WHILE or FOR expressions.
  2352.  
  2353.      The <field> and WITH <expr> must have the same data type.
  2354.  
  2355.      If replacements are made on a key field of an  index file will update the
  2356.      index file if it's  in use.  Thus  the <scope>, WITH, and  FOR conditions
  2357.      will not operate properly as the record order  will change as the records
  2358.      are replaced.   The  records should  be  replaced in  natural order  when
  2359.      replacing more than a single record.
  2360.  
  2361.      REPLACE cannot be used with read only files.
  2362.  
  2363. Example:
  2364.      To raise all product costs by 10%:
  2365.  
  2366. USE product INDEX part_no
  2367. SET ORDER TO 0                     && Record ordering
  2368. REPLACE ALL part_no WITH part_no * 1.10
  2369.  
  2370. RESTORE
  2371.  
  2372.  
  2373. Function:
  2374.      RESTORE retrieves memory variables from a memory file.
  2375.  
  2376. Syntax:
  2377.      RESTORE FROM <filename>
  2378.  
  2379. Remarks:
  2380.      A .mem file extension is assumed unless otherwise specified.
  2381.  
  2382.      Any current memory variables with  the same name as  those being restored
  2383.      are overwritten.    The  RESTORed  variables  will have  the  same  scope
  2384.      (PUBLIC, PRIVATE) as when the were SAVEed.
  2385.  
  2386.      All current memory variables are retained when using RESTORE.
  2387.  
  2388. Example:
  2389. variable = "Hello"
  2390. SAVE TO memory
  2391. variable = ""
  2392.  
  2393.                                                                              36
  2394.  
  2395.  
  2396. RESTORE FROM memory
  2397. ? variable                                         Hello
  2398.  
  2399. See Also:
  2400.      SAVE, STORE
  2401.  
  2402. RETRY
  2403.  
  2404.  
  2405. Function:
  2406.      RETRY completes subroutine execution  and returns program control  to the
  2407.      command that called the subroutine.
  2408.  
  2409. Syntax:
  2410.      RETRY
  2411.  
  2412. Remarks:
  2413.      RETRY is used  mainly in  error recovery  where it  can repeat  a command
  2414.      until it is  successfully executed.   RETRY  will re-execute  the command
  2415.      that called the current  subroutine.  This  is in contrast to  the RETURN
  2416.      command that executes the command after the calling command.
  2417.  
  2418.      If a runtime error occurs in  a program that has a routine  defined by ON
  2419.      ERROR DO, then RETRY can be used to re-attempt the erroneous command when
  2420.      the error conditions are corrected.
  2421.  
  2422. Example:
  2423.      The following program will recover from the error:  File is already open.
  2424.  
  2425. ON ERROR DO recover
  2426. <commands>
  2427. USE customer
  2428. <commands>
  2429. RETURN
  2430.  
  2431. PROCEDURE recover
  2432.   IF ERROR() =  3
  2433.     CLOSE DATABASES
  2434.     RETRY                          && attempt to USE again
  2435.   ENDIF
  2436. RETURN
  2437.  
  2438. See Also:
  2439.      ERROR(), ON ERROR, RETURN
  2440.  
  2441. RETURN
  2442.  
  2443.  
  2444. Function:
  2445.      RETURN completes procedure execution  and returns program control  to the
  2446.      calling program.  The command after the calling command is then executed.
  2447.  
  2448. Syntax:
  2449.      RETURN [TO MASTER]
  2450.  
  2451. Remarks:
  2452.      The TO MASTER  option will  return program control  to the  highest level
  2453.      calling program.  This  allows a simple  method of RETURNing  from nested
  2454.      procedures.
  2455.  
  2456.                                                                              37
  2457.  
  2458.  
  2459.  
  2460.      If the  RETURN  command is  not  included  at the  end  of  a program  or
  2461.      procedure file a RETURN is assumed before the next PROCEDURE statement or
  2462.      the end of file.
  2463.  
  2464.      RETURN releases all PRIVATE variables of a procedure.
  2465.  
  2466. See Also:
  2467.      DO, PRIVATE
  2468.  
  2469. RUN
  2470.  
  2471.  
  2472. Function:
  2473.      RUN executes a DOS command from within dB Online.
  2474.  
  2475. Syntax:
  2476.      RUN|! <dos command>
  2477.  
  2478. Remarks:
  2479.      All parameters must be  included in <dos  command> above.  There  must be
  2480.      enough memory to shell another version of COMMAND.COM
  2481.  
  2482.      RUN is only available in the Registered and Pro versions of dB Online.
  2483.  
  2484. Example:
  2485.      To download a file using DSZ.exe with dB Online.
  2486.  
  2487. file = "data.zip"
  2488. command = "dsz " + file
  2489. ? "Please start you zmodem download"
  2490. RUN &command
  2491.  
  2492. SAVE
  2493.  
  2494.  
  2495. Function:
  2496.      SAVE stores all or part of the current set of  memory variables to a disk
  2497.      file.
  2498.  
  2499. Syntax:
  2500.      SAVE TO <filename> [ALL LIKE|EXCEPT <var name spec>]
  2501.  
  2502. Remarks:
  2503.      The default extension for <filename> is .MEM unless otherwise specified.
  2504.      If the ALL LIKE|EXCEPT option is not used  then all current variables are
  2505.      saved to disk.
  2506.      In <var name spec>, a question  mark (?) masks a single  character and an
  2507.      asterisk (*) masks any number of characters.
  2508.  
  2509. Example:
  2510.      To SAVE all memory variables beginning with 'user' to file.mem
  2511.  
  2512. SAVE TO file ALL LIKE user*
  2513.  
  2514. See Also:
  2515.      RESTORE, STORE
  2516.  
  2517.  
  2518.  
  2519.                                                                              38
  2520.  
  2521.  
  2522. SEEK
  2523.  
  2524. Function:
  2525.      SEEK searches for  the first record  in the  active index of  the current
  2526.      database whose key matches a specified expression.
  2527.  
  2528. Syntax:
  2529.      SEEK <cexpr>|<dexpr>|<nexpr>
  2530.  
  2531. Remarks:
  2532.      The expression must have the same data type as the active index key.
  2533.  
  2534.      For character searches, the result  of the search depends  on the setting
  2535.      of SET EXACT.  If SET EXACT is ON the  key expression would have to match
  2536.      the full length of the index  key.  However with SET EXACT  OFF a partial
  2537.      string will match the first occurrence in a index key.
  2538.  
  2539.      If the search is successful the FOUND() flag is  set to True(.T.). If the
  2540.      search is unsuccessful the  record pointer moves  to the end of  the file
  2541.      and FOUND() is set to False (.F.).
  2542.  
  2543. Example:
  2544. USE customer INDEX name
  2545. SET EXACT OFF
  2546. SEEK "Smi"
  2547. ? name                                             Smith
  2548. SET EXACT ON
  2549. SEEK "Smi"
  2550. ? FOUND()                                          .F.
  2551.  
  2552. See Also:
  2553.      EOF(), FOUND(), LOCATE, SET DELETED, SET INDEX, SET EXACT, SET ORDER, USE
  2554.  
  2555.  
  2556. SELECT
  2557.  
  2558. Function:
  2559.      SELECT chooses a work area from the twenty available work areas.
  2560.  
  2561. Syntax:
  2562.      SELECT <integer>|<alias>
  2563.  
  2564. Remarks:
  2565.      Work areas are <integers>  numbered from 1 to  20, or A through  J (Alpha
  2566.      aliasing can only  access the first  10 work areas).   When you  start up
  2567.      your dB Online application, the active work area is  one.  Only dB Online
  2568.      Pro has access to more than a single work area.
  2569.  
  2570.      Each work area  can contain  one open database  file and  it's associated
  2571.      index and memo files.   You can use  SELECT to change work  areas so that
  2572.      the database in the new work area becomes the active database file.
  2573.  
  2574.      You can also use SELECT by  specifying the <alias> of a work  area.  This
  2575.      <alias> is specified  when the  database is  opened with  the USE...ALIAS
  2576.      command.  If  the ALIAS command  is not  used then the  database filename
  2577.      minus the extension is the default alias name.
  2578.  
  2579.  
  2580.  
  2581.  
  2582.                                                                              39
  2583.  
  2584.  
  2585.      Each work area maintains its  own record pointer and  moving between work
  2586.      areas does not  affect the  position of  any record  pointers.   All work
  2587.      areas operate  independently  of  each  other  unless  related  with  SET
  2588.      RELATION TO.
  2589.  
  2590.      Fields in the current work are accessed by  simply indicating their field
  2591.      name.  To access fields from  other work areas you can  specify fields in
  2592.      other work areas by using the aliasing indicator:
  2593.  
  2594.           alias->field      or      alias.field
  2595.  
  2596. Example:
  2597. SELECT a
  2598. USE customer
  2599. ? name                                             Smith
  2600. SELECT 2
  2601. USE sales
  2602. ? a->name
  2603. Outputs: Smith
  2604. ? subtotal                                         23.45
  2605.  
  2606. See Also:
  2607.      SET INDEX, USE
  2608.  
  2609. SET ALTERNATE
  2610.  
  2611.  
  2612. Function:
  2613.      SET ALTERNATE records all output other than  that of full-screen commands
  2614.      to a text file.
  2615.  
  2616. Syntax:
  2617.      SET ALTERNATE on/OFF
  2618.      SET ALTERNATE TO [<filename>]
  2619.  
  2620. Remarks:
  2621.      SET ALTERNATE is OFF by default.
  2622.  
  2623.      This command consists of two parts:
  2624.  
  2625.      SET ALTERNATE  TO <filename>  creates and  opens an  ALTERNATE file.   It
  2626.      overwrites any file with the same name.  A .TXT file extension is assumed
  2627.      unless otherwise specified.
  2628.  
  2629.      SET ALTERNATE ON starts recording of text output to  the text file.  Full
  2630.      screen commands such as @..SAY...GET are not recorded.
  2631.  
  2632.      SET ALTERNATE OFF suspends  the recording of  output to the  file without
  2633.      closing the file.  Recording can be restarted with SET ALTERNATE ON.
  2634.  
  2635.      The file is closed  with the SET  ALTERNATE TO command or  the equivalent
  2636.      CLOSE ALTERNATE.
  2637.  
  2638. Example:
  2639.      To flag a file to be downloaded in PCBoard:
  2640.  
  2641. file = "program.zip"
  2642. SET ALTERNATE TO pcbstuff.kbd
  2643. SET ALTERNATE ON
  2644.  
  2645.                                                                              40
  2646.  
  2647.  
  2648. SET CONSOLE OFF                    && To avoid output to screen
  2649. ?? "FLAG " + file
  2650. ?
  2651. SET CONSOLE ON
  2652. SET ALTERNATE TO                   &&Closes pcbstuff.kbd
  2653.  
  2654. See Also:
  2655.      CLOSE
  2656.  
  2657. SET BELL
  2658.  
  2659.  
  2660. Function:
  2661.      SET BELL determines whether a  bell is sounded when an  invalid data type
  2662.      is entered in an entry field or the end of an input area is reached.
  2663.  
  2664. Syntax:
  2665.      SET BELL ON|off
  2666.  
  2667. Remarks:
  2668.      SET BELL is ON by default
  2669.  
  2670. See Also:
  2671.      @...SAY...GET, SET CONFIRM
  2672.  
  2673. SET CENTURY
  2674.  
  2675.  
  2676. Function:
  2677.      SET CENTURY allows the input and display of centuries in the year portion
  2678.      of dates.
  2679.  
  2680. Syntax:
  2681.      SET CENTURY on|OFF
  2682.  
  2683. Remarks:
  2684.      SET CENTURY is OFF by default.
  2685.  
  2686.      Date display and entry will only allow for  6 significant digits when SET
  2687.      CENTURY is OFF.   Thus all  dates entered  will default to  the twentieth
  2688.      century.   However  any date  calculation  that  result in  non-twentieth
  2689.      century dates will be stored with the correct century.
  2690.  
  2691.      With SET  CENTURY ON  date display  and  entry will  allow 8  significant
  2692.      digits.  Thus century information can be fully specified.
  2693.  
  2694. Example:
  2695.  
  2696. ? DATE()                                           10/21/93
  2697. SET CENTURY ON
  2698. ? DATE()                                           10/21/1993
  2699.  
  2700. See Also:
  2701.      CTOD(), DATE(), DTOC(), YEAR()
  2702.  
  2703.  
  2704. SET COLOR
  2705.  
  2706. Function:
  2707.  
  2708.                                                                              41
  2709.  
  2710.  
  2711.      SET COLOR allows  custom color selection  for both standard  and enhanced
  2712.      output.
  2713.  
  2714. Syntax:
  2715.      SET COLOR TO [<standard>[,<enhanced>]]
  2716.  
  2717. Remarks:
  2718.      SET COLOR is only operational in ANSI terminal operation.  The <standard>
  2719.      colors are used for normal text output and the <enhanced> colors are used
  2720.      for @...GET input fields and error message outputs.
  2721.  
  2722.      The default colors upon startup are:         Standard: White on Black
  2723.                                                   Enhanced: Black on White
  2724.  
  2725.      SET COLOR TO <Enter> will re-select the default colors.
  2726.  
  2727.      The <standard> and <enhanced> colors are specified as follows:
  2728.  
  2729.                   Color     Letter     Intense    Letter
  2730.                             Code       Color      Code
  2731.                   Black     N or blank Dark Gray  N+
  2732.  
  2733.                   Blue      B          Light Blue B+
  2734.                   Red       R          Light Red  R+
  2735.                   Green     G          Light      G+
  2736.                                        Green
  2737.  
  2738.                   Cyan      BG         Light Cyan BG+
  2739.                   Magenta   RB         Light      RB+
  2740.                                        Magenta
  2741.  
  2742.                   Brown     GR         Yellow     GR+
  2743.                   Light GrayRGB or W   White      RGB+ or W+
  2744.                   Blank     X          Flashing   *
  2745.  
  2746.  
  2747.      Foreground and  background colors  are separated  by  a slash  (/).   The
  2748.      intense colors are only available in the foreground.   If an asterisk (*)
  2749.      is present then the output will be flashing.
  2750.  
  2751.      The Blank  (X) color  specifier will  output blank  characters.   This is
  2752.      useful for password entry.
  2753.  
  2754. Examples:
  2755.      The following SET COLOR commands are explained:
  2756.  
  2757. * Standard: Yellow on a Red background. Enhanced: White on a Red background.
  2758. SET COLOR TO GR+/R,W/R
  2759. * Standard: White on a Blue background. Enhanced: Black on a Cyan background.
  2760. SET COLOR TO W+/B,N/BG
  2761.  
  2762. See Also:
  2763.      ISCOLOR(), SET INTENSITY
  2764.  
  2765.  
  2766.  
  2767.  
  2768.  
  2769.  
  2770.  
  2771.                                                                              42
  2772.  
  2773.  
  2774. SET CONFIRM
  2775.  
  2776. Function:
  2777.      SET CONFIRM determines whether the cursor moves automatically to the next
  2778.      entry field when the  current field is  full.  This command  affects only
  2779.      full screen functions.
  2780.  
  2781. Syntax:
  2782.      SET CONFIRM on|OFF
  2783.  
  2784. Remarks:
  2785.      SET CONFIRM is OFF by  default.  This causes the  cursor to automatically
  2786.      advance from  one field  to  the next  in  a full  screen  @...GET   READ
  2787.      command.
  2788.  
  2789.      SET CONFIRM ON causes the cursor to remain in the field until the <Enter>
  2790.      key is pressed.
  2791.  
  2792. See Also:
  2793.      @...SAY...GET, SET BELL
  2794.  
  2795.  
  2796. SET CONSOLE
  2797.  
  2798. Function:
  2799.      SET CONSOLE determines  whether output  is sent to  the local  and remote
  2800.      terminals.
  2801.  
  2802. Syntax:
  2803.      SET CONSOLE ON|off
  2804.  
  2805. Remarks:
  2806.      SET CONSOLE is ON by default.   This causes all output to  be sent to the
  2807.      local and remote terminals.
  2808.  
  2809.      SET CONSOLE OFF does not send output to either local or remote terminals.
  2810.      This is useful for writing files to disk with SET ALTERNATE.
  2811.  
  2812. See Also:
  2813.      SET ALTERNATE
  2814.  
  2815.  
  2816. SET DECIMALS
  2817.  
  2818. Function:
  2819.      SET DECIMALS determines the minimum number of decimals to display for the
  2820.      results of numeric calculations.
  2821.  
  2822. Syntax:
  2823.      SET DECIMALS TO <nexpr>
  2824.  
  2825. Remarks:
  2826.      SET DECIMALS is set to 2 by default.
  2827.  
  2828.      SET DECIMALS  applies to  division, exponents,  EXP(), LOG(),  SQRT() and
  2829.      VAL() functions.  If SET FIXED is ON, SET DECIMALS applies to all numeric
  2830.      output.
  2831.  
  2832.  
  2833.  
  2834.                                                                              43
  2835.  
  2836.  
  2837. Example:
  2838.  
  2839. SET DECIMALS TO 2
  2840. ? 1/4                                                   0.25
  2841. ? 1/4.000                                               0.250
  2842. ? SQRT(3.452)                                           1.86
  2843. SET DECIMALS TO 5
  2844. ? 1/4                                                   0.25000
  2845.  
  2846. See Also:
  2847.      SET FIXED
  2848.  
  2849. SET DEFAULT
  2850.  
  2851.  
  2852. Function:
  2853.      SET DEFAULT determines  the default  drive to  where all  operations take
  2854.      place and files are stored unless otherwise specified.
  2855.  
  2856. Syntax:
  2857.      SET DEFAULT TO <drive>
  2858.  
  2859. Remarks:
  2860.      SET DEFAULT is set to the drive that dB Online was started up from.
  2861.  
  2862.      SET DEFAULT does not check if the given disk drive exists and it does not
  2863.      change the default drive when dB Online exits.
  2864.  
  2865. Example:
  2866.      To set the default drive to D:
  2867.  
  2868.      SET DEFAULT TO d
  2869.  
  2870. See Also:
  2871.      SET PATH
  2872.  
  2873. SET DELETED
  2874.  
  2875.  
  2876. Function:
  2877.      SET DELETED determines whether  records marked for deletion  are included
  2878.      in the execution of dB Online commands.
  2879.  
  2880. Syntax:
  2881.      SET DELETED on|OFF
  2882.  
  2883. Function:
  2884.      SET DELETED is OFF by default.
  2885.  
  2886.      With SET DELETED ON, most commands will not  recognize records marked for
  2887.      delete as part of  the database.  Commands  like LOCATE or LIST  will not
  2888.      display deleted records.   Commands  that specify  a record  number using
  2889.      RECORD <n> or GO|GOTO <n> will included deleted records.
  2890.  
  2891. See Also:
  2892.      DELETE, DELETED(), RECALL
  2893.  
  2894.  
  2895.  
  2896.  
  2897.                                                                              44
  2898.  
  2899.  
  2900. SET DELIMITERS
  2901.  
  2902. Function:
  2903.      SET DELIMITERS determines how fields are indicated in full-screen editing
  2904.      mode.
  2905.  
  2906. Syntax:
  2907.      SET DELIMITERS on|OFF
  2908.      SET DELIMITERS TO [<cexpr>|DEFAULT]
  2909.  
  2910. Remarks:
  2911.      SET DELIMITERS is  OFF by default.   This causes  entry fields not  to be
  2912.      enclosed by delimiter characters.   If SET INTENSITY is  ON, entry fields
  2913.      are display in enhanced colors.
  2914.  
  2915.      SET DELIMITERS ON will enclose entry fields by  the default delimiters of
  2916.      colons (:).
  2917.  
  2918.      SET DELIMITERS TO <cexpr> changes the default delimiter characters.  If a
  2919.      single character  is  specified  then it  is  used  to delimit  both  the
  2920.      beginning and end of  the entry field.   If two characters  are specified
  2921.      then the first  marks the beginning  and the second  marks the end.   Any
  2922.      extra characters are ignored.
  2923.  
  2924.      SET DELIMITERS TO DEFAULT returns the delimiters to colons (:)
  2925.  
  2926. See Also:
  2927.      @...SAY...GET, SET INTENSITY
  2928.  
  2929.  
  2930.  
  2931. SET ESCAPE
  2932.  
  2933. Function:
  2934.      SET  ESCAPE   determines  whether   pressing     <Esc>             terminates   
  2935.      execution.
  2936.  
  2937. Syntax:
  2938.      SET ESCAPE ON|off
  2939.  
  2940. Remarks:
  2941.      SET ESCAPE  is ON  by default.    This causes  the dB  Online program  to
  2942.      terminate when the user presses the  <Esc>   key.  Escape key trapping with
  2943.      ON ESCAPE is only available with SET ESCAPE ON.
  2944.  
  2945.      With SET ESCAPE OFF  the  <Esc>   key does not terminate program execution.
  2946.      The keypress may be determined  like any other keypress  with the INKEY()
  2947.      function.
  2948.  
  2949. See Also:
  2950.      INKEY(), ON ESCAPE, READKEY()
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.                                                                              45
  2961.  
  2962.  
  2963. SET EXACT
  2964.  
  2965. Function:
  2966.      SET EXACT determines whether  a comparison between two  character strings
  2967.      requires an exact match.
  2968.  
  2969. Syntax:
  2970.      SET EXACT on|OFF
  2971.  
  2972. Remarks:
  2973.      SET EXACT is OFF by default.  This causes character string comparisons to
  2974.      be True (.T.) if the strings are identical up to the length of the second
  2975.      string.
  2976.  
  2977.      With SET EXACT ON the character strings must be exactly the same before a
  2978.      True (.T.) is returned.
  2979.  
  2980.      SET EXACT also applies to the SEEK command with character index keys.
  2981.  
  2982. Examples:
  2983.  
  2984. SET EXACT OFF
  2985. ? "abc" = "abcdef"                                 .F.
  2986. ? "abcdef" = "abc"                                 .T.
  2987. SET EXACT ON
  2988. ? "abcdef" = "abc"                                 .F.
  2989.  
  2990. See Also:
  2991.      LOCATE, SEEK, =
  2992.  
  2993.  
  2994. SET EXCLUSIVE
  2995.  
  2996. Function:
  2997.      SET EXCLUSIVE  allows the  shared use  of database  file on  a multi-user
  2998.      system.
  2999.  
  3000. Syntax:
  3001.      SET EXCLUSIVE ON/off
  3002.  
  3003. Remarks:
  3004.      SET EXCLUSIVE  is ON  by default.   This  means that  all data  files are
  3005.      opened in exclusive  mode.  Any  other user  attempting to open  the will
  3006.      receive an error.
  3007.  
  3008.      SET EXCLUSIVE OFF enables  multi-user access to  the database files.   dB
  3009.      Online will  provide file  and record  locking  for database  files in  a
  3010.      method native to your DataBase Management System.
  3011.  
  3012. See Also:
  3013.      FLOCK(), LOCK(), RLOCK(), SET LOCK, SET REPROCESS, UNLOCK, USE
  3014.  
  3015.  
  3016. SET FILTER
  3017.  
  3018. Function:
  3019.      SET FILTER  allows only  records that  meet a  specified condition  to be
  3020.      displayed.
  3021.  
  3022.  
  3023.                                                                              46
  3024.  
  3025.  
  3026.  
  3027. Syntax:
  3028.      SET FILTER TO [<lexpr>]
  3029.  
  3030. Remarks:
  3031.      All commands that access database records can be used with the SET FILTER
  3032.      TO <lexpr> condition.
  3033.  
  3034.      SET FILTER  only applies  to  the current  database  work area.   Thus  a
  3035.      different condition may be set for each work area.
  3036.  
  3037.      All records for which <lexpr> is True (.T.)  are available for processing
  3038.      and any for which <lexpr> is False (.F.) are ignored.
  3039.  
  3040.      Filter conditions are not valid  until the record pointer  is moved after
  3041.      the SET FILTER TO command is executed.  You must move your record pointer
  3042.      with GOTO TOP or SKIP to ensure the filter condition is valid.
  3043.  
  3044.      SET FILTER TO      <Cr>      turns  of a  filter for the  current work  area.  A
  3045.      records are then available for processing.
  3046.  
  3047. Example:
  3048.      To count the number of customers in New York:
  3049.  
  3050. USE customer
  3051. SET FILTER TO state = "NY"
  3052. COUNT TO number
  3053.  
  3054.      To total all sales in October 1993:
  3055.  
  3056. USE sales
  3057. SET FILTER TO MONTH(saledate) = 10 .AND. YEAR(saledate) = 1993
  3058. SUM price * quantity TO total
  3059.  
  3060. See Also:
  3061.      SET DELETED
  3062.  
  3063. SET FIXED
  3064.  
  3065.  
  3066. Function:
  3067.      SET FIXED  determines  whether  a  fixed  number of  decimal  places  are
  3068.      displayed for all numeric output.
  3069.  
  3070. Syntax:
  3071.      SET FIXED on|OFF
  3072.  
  3073. Remarks:
  3074.      SET FIXED is OFF  by default.  This  causes the number of  decimal places
  3075.      for numeric output to be as explained in the SET DECIMALS command.
  3076.  
  3077.      If SET FIXED  is ON all  numeric output will  have the number  of decimal
  3078.      places identified by SET DECIMALS TO.
  3079.  
  3080. See Also:
  3081.      SET DECIMALS
  3082.  
  3083.  
  3084.  
  3085.  
  3086.                                                                              47
  3087.  
  3088.  
  3089. SET INDEX
  3090.  
  3091. Function:
  3092.      SET INDEX opens specified index files in the current work area.
  3093.  
  3094. Syntax:
  3095.      SET INDEX TO [<filename> [,<filename>]...]
  3096.  
  3097. Remarks:
  3098.      The  default  file  extension  is  determined   by  which  database  file
  3099.      compatibility you  have  chosen with  dB  Online.   For  dBASE III+   file
  3100.      compatibility the default extension is .NDX, for Clipper:  .NTX
  3101.                                                                    ,  for dBASE
  3102.      IV: .MDX, and for FoxPro: .CDX
  3103.  
  3104.      SET INDEX closes all indexes in the current  work area before opening the
  3105.      ones specified in the file list.  SET INDEX TO  <Cr>   will close all index
  3106.      file in the current work area and is equivalent to CLOSE INDEX.
  3107.  
  3108.      The first tag of the first index file  specified becomes the master  index
  3109.      for the current  database (Tags do  not apply  to dBASE  III+  and Clipper
  3110.      file compatibility).   The master  index determines  the record  order as
  3111.      well as  the search  key for  the SEEK  command.   The record  pointer is
  3112.      positioned at the first logical record of the index key.
  3113.  
  3114.      All open index  files are  updated when  changes are  made to  a database
  3115.      file.
  3116.  
  3117. See Also:
  3118.      SET ORDER, USE
  3119.  
  3120.  
  3121. SET INTENSITY
  3122.  
  3123. Function:
  3124.      SET INTENSITY determines whether the enhanced screen  colors are used for
  3125.      full screen data entry fields.
  3126.  
  3127. Syntax:
  3128.      SET INTENSITY ON/off
  3129.  
  3130. Remarks:
  3131.      SET INTENSITY is ON by default.   This causes all full  screen data entry
  3132.      fields (@...GETs)  to  be  displayed  in  the enhanced  screen  color  as
  3133.      determined by SET COLOR  TO.  All other  text output is displayed  in the
  3134.      standard screen color.
  3135.  
  3136.      If SET INTENSITY is OFF, then  the standard screen color is  used for all
  3137.      data output.
  3138.  
  3139. See Also:
  3140.      @...SAY...GET, SET COLOR, SET DELIMITERS
  3141.  
  3142.  
  3143.  
  3144.  
  3145.  
  3146.  
  3147.  
  3148.  
  3149.  
  3150.                                                                              48
  3151.  
  3152.  
  3153. SET LOCK
  3154.  
  3155. Function:
  3156.      SET LOCK allows the current record of a database file to be locked before
  3157.      reading.
  3158.  
  3159. Syntax:
  3160.      SET LOCK on/OFF
  3161.  
  3162. Remarks:
  3163.      SET LOCK is OFF  by default.   This mean that  records are not  locked as
  3164.      they are read into the record buffer.  This allows users to view the same
  3165.      record simultaneously.
  3166.  
  3167.      With SET LOCK  ON, any  record is  automaticallly locked  before reading.
  3168.      This ensures that there  can be no changed  to the data once  it is read.
  3169.      While this  greatly  simplifies  creating  multi-user applications.    It
  3170.      increases the chances that another user will have to wait for a record if
  3171.      he only wants to view it.
  3172.  
  3173. See Also:
  3174.      FLOCK(), LOCK(), RLOCK(), SET EXCLUSIVE, SET REPROCESS,  UNLOCK
  3175.  
  3176.  
  3177. SET MEMOWIDTH
  3178.  
  3179. Function:
  3180.      SET MEMOWIDTH determines the width for memo field output.
  3181.  
  3182. Syntax:
  3183.      SET MEMOWIDTH TO <nexpr>
  3184.  
  3185. Remarks:
  3186.      SET MEMOWIDTH TO has a default value of 50 by default.  The minimum value
  3187.      is 8 characters.
  3188.  
  3189.      All memo  output using  the ?   |??  or LIST|DISPLAY  commands will  be word
  3190.      wrapped within a column width defined by SET MEMOWIDTH TO.
  3191.  
  3192.  
  3193. SET ORDER 
  3194.  
  3195. Function:
  3196.      SET ORDER sets up an open index file as the master index.
  3197.  
  3198. Syntax:
  3199.      SET ORDER TO [<nexpr> | TAG <tag>]
  3200.  
  3201. Remarks:
  3202.      SET ORDER TO changes the master index from the available index tags.
  3203.  
  3204.      If SET ORDER  TO <nexpr> is  used then the  master index becomes  the tag
  3205.      corresponding to the value of  <nexpr>.  For  dBASE III+ and  Clipper   file
  3206.      compatibility  this  number  corresponds   to  the  index  file   on  the
  3207.      USE...INDEX or SET INDEX TO list.  For  dBASE IV and FoxPro   compatibility
  3208.      it corresponds to the all the tags of the index file list.
  3209.  
  3210.  
  3211.  
  3212.  
  3213.                                                                              49
  3214.  
  3215.  
  3216.      If SET ORDER TO TAG <tag> is used then a search is made for the first tag
  3217.      whose name matches <tag>.   The tag names for dBASEIII  and Clipper index
  3218.      files correspond to the index file names without the filename extension.
  3219.  
  3220.      SET ORDER TO 0 returns the database to natural record ordering.
  3221.  
  3222. See Also:
  3223.      CDX(), MDX(), NDX(), SET INDEX
  3224.  
  3225. SET PATH
  3226.  
  3227.  
  3228. Function:
  3229.      SET PATH determines the directories  dB Online will search  to find files
  3230.      not in the current directory.
  3231.  
  3232. Syntax:
  3233.      SET PATH TO [<path list>]
  3234.  
  3235. Remarks:
  3236.      By default dB  Online only searches  the current  directory.  If  a <path
  3237.      list> is  specified dB  Online  will search  for  a file  in the  current
  3238.      directory first and then in the directories specified.
  3239.  
  3240.      The <path list> consists  of a list of  paths separated by commas  (,) or
  3241.      semi-colons (;).
  3242.  
  3243.      SET PATH applies only to commands that search for existing files.  If you
  3244.      create a file it  will be saved in  the current directory unless  the you
  3245.      specify the path with the filename.
  3246.  
  3247. Examples:
  3248.      The following program will search in two directories  if a file cannot be
  3249.      found in the default directory.
  3250.  
  3251. SET PATH TO c:\dbonline\databases,c:\foxpro\files
  3252. use customer
  3253.  
  3254. See Also:
  3255.      FILE(), SET DEFAULT
  3256.  
  3257. SET PROCEDURE 
  3258.  
  3259.  
  3260. Function:
  3261.      SET PROCEDURE is used to  include procedure files while a  source file is
  3262.      being compiled.
  3263.  
  3264. Syntax:
  3265.      SET PROCEDURE TO [<filename>]
  3266.  
  3267. Remarks:
  3268.      SET PROCEDURE TO specifies filenames to be included with the current main
  3269.      file.  All source files are  compiled and a single .DBX  file is created.
  3270.      Thus it is not necessary to CLOSE PROCEDURE files.   The SET PROCEDURE TO
  3271.      command is not present at runtime.
  3272.  
  3273.      See the Compiling section for more details on SET PROCEDURE.
  3274.  
  3275.  
  3276.                                                                              50
  3277.  
  3278.  
  3279. See Also:
  3280.      DO, PARAMETERS
  3281.  
  3282. SET RELATION
  3283.  
  3284.  
  3285. Function:
  3286.      SET RELATION links two open database files according  to a key expression
  3287.      that is common to both files.
  3288.  
  3289. Syntax:
  3290.      SET RELATION TO [<key expr>|<nexpr> INTO <alias>]
  3291.  
  3292. Remarks:
  3293.      SET RELATION TO links the  active database file to an  open database file
  3294.      in another work area.   The INTO file  is identified by its  alias.  Only
  3295.      one relation can be made from  each work area.  The  active database file
  3296.      is called the parent file, and the INTO file is called the child file.
  3297.  
  3298.      If a <key expression>  is used then  the child database must  be indexed.
  3299.      The <key expression>  is evaluated and  then a  seek is performed  on the
  3300.      child work area.  The child database is position to the first record that
  3301.      matches the key expression.
  3302.  
  3303.      When the <nexpr> is used, and the child database is not indexed, then the
  3304.      child database is positioned to the record number given by <nexpr>.
  3305.  
  3306.      If no record is found then the child database is positioned to the end of
  3307.      file and EOF() will return True (.T.).
  3308.  
  3309.      As the  parent  and child  files  must be  in  separate  work areas,  SET
  3310.      RELATION is only available in the Pro version of dB Online.
  3311.  
  3312. Example:
  3313.      If the invoice database has  a field inv_no which matches  the same field
  3314.      in sales we can set the following relation:
  3315.  
  3316. SELECT a
  3317. USE invoice.dbf
  3318. USE sales INDEX inv_no.ndx IN 2    && open sales in work area b
  3319. SELECT a
  3320. SET RELATION TO inv_no INTO b
  3321. LIST inv_no, customer, b->product, b->sales        && output related fieldS
  3322.  
  3323. See Also:
  3324.      SET INDEX, SET ORDER
  3325.  
  3326. SET REPROCESS
  3327.  
  3328.  
  3329. Function:
  3330.      SET REPROCESS determines how may times dB Online will attempt to access a
  3331.      locked record before returning an error.
  3332.  
  3333. Syntax:
  3334.      SET REPROCESS TO <nexpr>
  3335.  
  3336. Remarks:
  3337.  
  3338.  
  3339.                                                                              51
  3340.  
  3341.  
  3342.      SET REPROCESS is set  to -1 by default.   This means that  dB Online will
  3343.      attempt to open the locked data  approximately every second indefinately.
  3344.      Once the  data is  available, then  dB Online  will proceed  with program
  3345.      execution.
  3346.  
  3347.      If SET REPROCESS is set to any non-negative value, dB Online will attempt
  3348.      to open the locked data <nexpr> times.  These open attempts will occur at
  3349.      approximately one second intervals.  If SET REPROCESS is set to 0 then dB
  3350.      Online will immediately return a locking error.
  3351.  
  3352. See Also:
  3353.      FLOCK() , LOCK(), RLOCK(), SET LOCK, SET EXCLUSIVE, UNLOCK
  3354.  
  3355. SKIP
  3356.  
  3357.  
  3358. Function:
  3359.      SKIP moves the record pointer forward or backward in the current database
  3360.      file.
  3361.  
  3362. Syntax:
  3363.      SKIP [<nexpr>]
  3364.  
  3365. Remarks:
  3366.      SKIP uses the natural record order when moving the record pointer, unless
  3367.      there is an active  index file in use,  then SKIP follows the  index file
  3368.      order.
  3369.  
  3370.      SKIP moves the record pointer by the value of <nexpr>.  Both positive and
  3371.      negative values of  <nexpr> are allowed  with negative values  moving the
  3372.      record pointer backwards.  If <nexpr> is omitted, then the record pointer
  3373.      is moved a single record forward.
  3374.  
  3375.      If SKIP is used with a  positive value when the record pointer  is at the
  3376.      last record in the database, then the EOF() condition will be True (.T.).
  3377.  
  3378.      If SKIP is used with a  negative value when the record pointer  is at the
  3379.      first record  in the  database, then  the  BOF() condition  will be  True
  3380.      (.T.).
  3381.  
  3382. Example:
  3383.  
  3384. USE customer
  3385. SKIP
  3386. ? RECNO()                                                  2
  3387. SKIP 15
  3388. ? RECNO()                                                 17
  3389. SKIP -5
  3390. ? RECNO()                                                 12
  3391.  
  3392. See Also:
  3393.      BOF(), EOF(), GOTO
  3394.  
  3395. STORE
  3396.  
  3397.  
  3398. Function:
  3399.      STORE creates and assigns values to one or more memory variables.
  3400.  
  3401.  
  3402.                                                                              52
  3403.  
  3404.  
  3405. Syntax:
  3406.      STORE <expr> TO <var list>  or
  3407.      <var> = <expr>
  3408.  
  3409. Remarks:
  3410.      The value of <expr> is assigned  to all the variables in  <var list> when
  3411.      using the  STORE  command.   With  the alternate  syntax,  only a  single
  3412.      variable may be assigned at a time.
  3413.  
  3414.      You can not assign  values to fields using  the STORE command.   You must
  3415.      use the REPLACE command.
  3416.  
  3417. Example:
  3418.  
  3419. STORE 0 TO a,b,c                   && initialize a, b, c to zero
  3420. name = "Smith"                     && STORES 'Smith' to variable name
  3421.  
  3422. See Also:
  3423.      PRIVATE, PUBLIC
  3424.  
  3425. SUM
  3426.  
  3427.  
  3428. Function:
  3429.      SUM calculates the  total of numeric  expressions in the  active database
  3430.      file.
  3431.  
  3432. Syntax:
  3433.      SUM [<scope>] <expr list> TO <var list> [WHILE <lexpr>] [FOR <lexpr>]
  3434.  
  3435. Remarks:
  3436.      All records in the current  database are totaled unless  specified by the
  3437.      <scope>, WHILE, or FOR clauses.  The <expr list> items must correspond to
  3438.      the memory variables in <var list>.
  3439.  
  3440. Example:
  3441.      To output the total sales by John Smith:
  3442.  
  3443. USE sales
  3444. SUM quantity * price TO total FOR salesman = "JS"
  3445. ? total
  3446.  
  3447. See Also:
  3448.      AVERAGE, COUNT
  3449.  
  3450. TEXT
  3451.  
  3452.  
  3453. Function:
  3454.      TEXT is used to output blocks of text to the screen.
  3455.  
  3456. Syntax:
  3457.      TEXT
  3458.           <text>
  3459.           <text>
  3460.           ...
  3461.      ENDTEXT
  3462.  
  3463. Remarks:
  3464.  
  3465.                                                                              53
  3466.  
  3467.  
  3468.      The text is output exactly as  it appears in the source file.   The first
  3469.      text line that begins with ENDTEXT will terminate the output text.
  3470.  
  3471. Example:
  3472.      To output a short menu to the screen.
  3473.  
  3474. CLEAR
  3475. TEXT
  3476.      [S]     Search
  3477.      [L]     List
  3478.      [Q]     Quit
  3479.      [?]     Help
  3480.  
  3481.               Please enter your selection:
  3482. ENDTEXT
  3483.  
  3484. See Also:
  3485.      ?|??, @...SAY, DISPLAY, LIST
  3486.  
  3487. UNLOCK
  3488.  
  3489.  
  3490. Function:
  3491.      UNLOCK removes  locks  previously placed  on  a  datafile using  FLOCK(),
  3492.      LOCK(), or RLOCK().
  3493.  
  3494. Syntax:
  3495.      UNLOCK
  3496.  
  3497. Remarks:
  3498.      UNLOCK will unlock  the file  in the  current work  area.   UNLOCK allows
  3499.      other users to access all the information in a  database file.  It should
  3500.      be used  after the  commands that  required  file or  record locking  are
  3501.      completed.
  3502.  
  3503. Example:
  3504.  
  3505. USE customer.dbf
  3506. IF FLOCK()                         && if lock is successful
  3507.   PACK
  3508.   UNLOCK                           && unlock file after PACKing.
  3509. ELSE
  3510.   ? "Unable to lock file"
  3511.   QUIT
  3512. ENDIF
  3513.  
  3514. See Also:
  3515.      FLOCK(), LOCK(), RLOCK(), SET EXCLUSIVE, SET LOCK, SET REPROCESS
  3516.  
  3517.  
  3518.  
  3519.  
  3520.  
  3521.  
  3522.  
  3523.  
  3524.  
  3525.  
  3526.  
  3527.  
  3528.                                                                              54
  3529.  
  3530.  
  3531. USE
  3532.  
  3533. Function:
  3534.      USE opens an existing  database file and  any specified index files.   If
  3535.      the database includes  memo fields, then  the corresponding memo  file is
  3536.      opened.
  3537.  
  3538. Syntax:
  3539.      USE  [         <filename>          ]   [INDEX          <index   file  list>
  3540.      <integer>]
  3541.  
  3542. Remarks:
  3543.      Unless otherwise specified  dB Online  assumes a  .DBF extension  for the
  3544.      database file while the default index file extension  is dependent on the
  3545.      file compatibility in use.
  3546.  
  3547.      All index files  in the <index  file list>  are opened with  the database
  3548.      file.  In dBASE IV  and 
  3549.                             FoxPro  file compatibility if there is a production
  3550.      index file associated with the database file it is opened automatically.
  3551.  
  3552.      USE         <Cr>          will  close  the  database and  index  files  in the  
  3553.      selected work area.
  3554.  
  3555.      If the ALIAS  option is  omitted   , then  dB Online  will use  the database
  3556.      filename minus the extension for the ALIAS.
  3557.  
  3558.      The files are  opened in  the currently selected  work area.   If  the IN
  3559.      command is  used, then  dB Online  switches  to the  specified work  area
  3560.      before attempting to open any files.
  3561.  
  3562. Example:
  3563.  
  3564. SELECT 1
  3565. USE customer                       && open customer.dbf in work area 1
  3566. USE sales INDEX part_no IN 2       && open sales in work area 2
  3567. SELECT customer                    && select customer.dbf using alias
  3568.  
  3569. See Also:
  3570.      CLOSE, SELECT, SET EXCLUSIVE, SET INDEX
  3571.  
  3572.  
  3573. WAIT
  3574.  
  3575. Function:
  3576.      WAIT pauses until  a single key  in input on  either the remote  or local
  3577.      terminals.
  3578.  
  3579. Syntax:
  3580.      WAIT [<cexpr>] [TO <var>]
  3581.  
  3582. Remarks:
  3583.      WAIT displays the optional prompt <cexpr> before waiting for a user
  3584.      keypress.  If no prompt is specified then "Press any key to continue..."
  3585.      is displayed.
  3586.  
  3587.      If the optional <var> is specified then the character input is placed
  3588.      into <var>.  If <Cr> or other non-printable character is entered, a null
  3589.      string is assigned to <var>.
  3590.  
  3591.  
  3592.                                                                              55
  3593.  
  3594.  
  3595.  
  3596. Example:
  3597.  
  3598. WAIT 'Do you wish to continue (Y/N)' TO answer
  3599. IF UPPER(answer) = 'N'
  3600.   QUIT
  3601. ENDIF
  3602.  
  3603. See Also:
  3604.      ON ESCAPE
  3605.  
  3606.  
  3607.  
  3608.  
  3609.  
  3610.  
  3611.  
  3612.  
  3613.  
  3614.  
  3615.  
  3616.  
  3617.  
  3618.  
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  
  3624.  
  3625.  
  3626.  
  3627.  
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.  
  3635.  
  3636.  
  3637.  
  3638.  
  3639.  
  3640.  
  3641.  
  3642.  
  3643.  
  3644.  
  3645.  
  3646.  
  3647.  
  3648.  
  3649.  
  3650.  
  3651.  
  3652.  
  3653.  
  3654.  
  3655.                                                                              56
  3656.  
  3657.  
  3658. Database Functions
  3659.  
  3660.  
  3661. &
  3662.  
  3663. Function:
  3664.      & is the macro substitution  function.  It substitutes the  contents of a
  3665.      character memory variable for another variable name or a file name.
  3666.  
  3667. Syntax:
  3668.      &<var>
  3669.  
  3670. Return Value:
  3671.      <var>|<field>|<filename>
  3672.  
  3673. Remarks:
  3674.      The  contents  of  <var>  will  specify   either  another  variable/field
  3675.      identifier or a file name to be used in a file command.
  3676.  
  3677. Examples:
  3678.      To macro substitute a variable name:
  3679.  
  3680. x = "hello"
  3681. hello = 10
  3682. ? x                                                hello
  3683. ? &x                                               10
  3684.  
  3685.      To macro substitute a file name:
  3686.  
  3687. x = "customer.dbf"
  3688. use &x                             &&Opens customer.dbf
  3689.  
  3690.  
  3691. ABS()
  3692.  
  3693.  
  3694. Function:
  3695.      The ABS() function returns the absolute value of a numeric expression.
  3696.  
  3697. Syntax:
  3698.      ABS(<nexpr>)
  3699.  
  3700. Return Value:
  3701.      NUMERIC
  3702.  
  3703. Example:
  3704.  
  3705. ? ABS(3)                                           3
  3706. ? ABS(-3)                                          3
  3707.  
  3708. ASC()
  3709.  
  3710.  
  3711. Function:
  3712.      The ASC() function returns  the ASCII value  of the first character  in a
  3713.      character expression.
  3714.  
  3715. Syntax:
  3716.      ASC(<cexpr>)
  3717.  
  3718.                                                                              57
  3719.  
  3720.  
  3721.  
  3722. Return Value:
  3723.      NUMERIC
  3724.  
  3725. Remarks:
  3726.      Returns the ASCII value of the first character in  <cexpr> in the range 0
  3727.      to 255.  If  the length of <cexpr> is 0 then ASC() returns 0.
  3728.  
  3729. Example:
  3730. ? ASC('A')                                         65
  3731. ? ASC("Hello")                                     72
  3732.  
  3733. See Also:
  3734.      CHR()
  3735.  
  3736. AT()
  3737.  
  3738.  
  3739. Function:
  3740.      The AT() function returns the starting position of a character string
  3741.      within a second string.
  3742.  
  3743. Syntax:
  3744.      AT(<cexpr1>,<cexpr2>)
  3745.  
  3746. Return Value:
  3747.      NUMERIC
  3748.  
  3749. Remarks:
  3750.      Returns the character offset in <cexpr1> where <cexpr2> is contained.  If
  3751.      <cexpr2> is not contained then 0 is returned.
  3752.  
  3753. Examples:
  3754.  
  3755. ? AT("Hi there John","there")                      4
  3756.  
  3757. WAIT TO x
  3758. responses = "123456"
  3759. IF AT(responses,x) =0
  3760.   ?"Invalid Choice"
  3761. ENDIF
  3762.  
  3763. See Also:
  3764.      SUBSTR()
  3765.  
  3766. BOF()
  3767.  
  3768.  
  3769. Function:
  3770.      The BOF() function indicates the beginning of the current database file.
  3771.  
  3772. Syntax:
  3773.      BOF()
  3774.  
  3775. Return Value:
  3776.      LOGICAL
  3777.  
  3778. Remarks:
  3779.  
  3780.  
  3781.                                                                              58
  3782.  
  3783.  
  3784.      Returns a logical True (.T.) when an attempt is made to move the record
  3785.      pointer before the first logical record of the current database file.
  3786.  
  3787. Example:
  3788.  
  3789. USE customer
  3790. ? BOF()                                            .F.
  3791. SKIP -1
  3792. ? BOF()                                            .T.
  3793.  
  3794. See Also:
  3795.      EOF()
  3796.  
  3797. CDOW()
  3798.  
  3799.  
  3800. Function:
  3801.      The CDOW() function returns the character name of the day of the week
  3802.      from a date expression.
  3803.  
  3804. Syntax:
  3805.      CDOW(<dexpr>)
  3806.  
  3807. Return Value:
  3808.      CHARACTER
  3809.  
  3810. Examples:
  3811.      If the system date = 10/21/93
  3812.  
  3813. ? CDOW(DATE())                                     Thursday
  3814. ? CDOW(DATE()+1)                                   Friday
  3815.  
  3816. See Also:
  3817.      DAY(), DOW()
  3818.  
  3819. CDX()
  3820.  
  3821.  
  3822. Function:
  3823.      The CDX() function returns the filename for the active index files in a
  3824.      work area.
  3825.  
  3826. Syntax:
  3827.      CDX(<nexpr1>[,<nexpr2>|<alias>])
  3828.  
  3829. Return Value:
  3830.      CHARACTER
  3831.  
  3832. Remarks:
  3833.      Returns the filename of an open .cdx file in a work area.  <nexpr1> is
  3834.      the .cdx file position in the index file list specified by the SET INDEX
  3835.      TO <file list>, or USE INDEX <file list> commands.  The optional second
  3836.      parameter returns .cdx files for other work areas.
  3837.  
  3838. Example:
  3839.  
  3840. USE customer INDEX name.cdx, phone.cdx
  3841. ? CDX(1)                                           c:name.cdx
  3842. ? CDX(2)                                           c:phone.cdx
  3843.  
  3844.                                                                              59
  3845.  
  3846.  
  3847.  
  3848. See Also:
  3849.      NDX(), MDX()
  3850.  
  3851. CHR()
  3852.  
  3853.  
  3854. Function:
  3855.      The CHR() function returns the character corresponding to an ASCII code
  3856.      value.
  3857.  
  3858. Syntax:
  3859.      CHR(<nexpr>)
  3860.  
  3861. Return Value:
  3862.      CHARACTER
  3863.  
  3864. Remarks:
  3865.      Returns a single character corresponding to the ASCII value of <nexpr>.
  3866.      If <nexpr> is 0 then CHR() returns an empty string.
  3867.  
  3868. Example:
  3869. ? CHR(65)                                          A
  3870. ? CHR(72)+CHR(105)                                 Hi
  3871.  
  3872. See Also:
  3873.      ASC(), INKEY()
  3874.  
  3875. CMONTH()
  3876.  
  3877.  
  3878. Function:
  3879.      The CMONTH() function returns the character name of the month from a date
  3880.      expression.
  3881.  
  3882. Syntax:
  3883.      CMONTH(<dexpr>)
  3884.  
  3885. Return Value:
  3886.      CHARACTER
  3887.  
  3888. Example:
  3889.      Assume the date is 10/21/93
  3890.  
  3891. ?  CMONTH(DATE())                                  October
  3892.  
  3893. See Also:
  3894.      MONTH()
  3895.  
  3896.  
  3897. COL()
  3898.  
  3899. Function:
  3900.      The COL() function returns the current column position on the remote and
  3901.      local screens.
  3902.  
  3903. Syntax:
  3904.      COL()
  3905.  
  3906.  
  3907.                                                                              60
  3908.  
  3909.  
  3910. Return Value:
  3911.      NUMERIC
  3912.  
  3913. Remarks:
  3914.      Returns current column position from 0 to 79.
  3915.  
  3916. Example:
  3917. ? "Hello"
  3918. ? col()                                            5
  3919.  
  3920. See Also:
  3921.      @...SAY...GET, ROW()
  3922.  
  3923. CTOD()
  3924.  
  3925.  
  3926. Function:
  3927.      The CTOD() function converts a character expression to a date value.
  3928.  
  3929. Syntax:
  3930.      CTOD(<cexpr>) or
  3931.      {<date>}
  3932.  
  3933. Return Value:
  3934.      DATE
  3935.  
  3936. Remarks:
  3937.      Returns a date value by converting <cexpr>.  The format of <cexpr> is
  3938.      mm/dd/yy with SET CENTURY OFF, or mm/dd/ccyy with SET CENTURY ON.
  3939.      The {} structure allows for date literals.  The syntax is {mm/dd/yy}.
  3940.  
  3941. Example:
  3942.  
  3943. STORE CTOD('02/28/93') to test
  3944. ? test                                             02/28/93
  3945. ? test +5                                          03/05/93
  3946.  
  3947. See Also:
  3948.      DTOC(), SET CENTURY
  3949.  
  3950. DATE()
  3951.  
  3952.  
  3953. Function:
  3954.      The DATE() function returns the current system date.
  3955.  
  3956. Syntax:
  3957.      DATE()
  3958.  
  3959. Return Value:
  3960.      DATE
  3961.  
  3962. Example:
  3963.       Assume the system date is 10/21/93
  3964.  
  3965. ? DATE()                                           10/21/93
  3966.  
  3967. See Also:
  3968.      DAY(), MONTH(), SET CENTURY, YEAR()
  3969.  
  3970.                                                                              61
  3971.  
  3972.  
  3973. DAY()
  3974.  
  3975. Function:
  3976.      The DAY() function returns the day of the month from a date expression.
  3977.  
  3978. Syntax:
  3979.      DAY(<dexpr>)
  3980.  
  3981. Return Value:
  3982.      NUMERIC
  3983.  
  3984. Example:
  3985.      If the system date is 10/21/93
  3986.  
  3987. ? DAY(DATE())                                      21
  3988.  
  3989. See Also:
  3990.      DATE(), MONTH(), YEAR()
  3991.  
  3992.  
  3993. DBF()
  3994.  
  3995. Function:
  3996.      The DBF() function returns the filename of the database in the current
  3997.      work area.
  3998.  
  3999. Syntax:
  4000.      DBF()
  4001.  
  4002. Return Value:
  4003.      CHARACTER
  4004.  
  4005. Remarks:
  4006.      Returns the full path used to specify the database in the current work
  4007. area.
  4008.  
  4009. Example:
  4010.  
  4011. USE customer
  4012. ? dbf()                                            c:customer.dbf
  4013.  
  4014. See Also:
  4015.      CDX(), FIELD(), LUPDATE(), MDX(), NDX(), RECCOUNT(), RECSIZE()
  4016.  
  4017.  
  4018. DELETED()
  4019.  
  4020. Function:
  4021.      The DELETED() function identifies records that are marked for deletion.
  4022.  
  4023. Syntax
  4024.      DELETED()
  4025.  
  4026. Return Value:
  4027.      LOGICAL
  4028.  
  4029. Remarks:
  4030.  
  4031.  
  4032.  
  4033.                                                                              62
  4034.  
  4035.  
  4036.      Returns True (.T.) if the current record is marked for deletion, if not,
  4037.      False (.F.) is returned.
  4038.  
  4039. Example:
  4040.  
  4041. USE customer
  4042. ? DELETED()                                        .F.
  4043. DELETE
  4044. ? DELETED()                                        .T.
  4045.  
  4046. See Also:
  4047.      DELETE, PACK, RECALL, SET DELETED ON
  4048.  
  4049. DISKSPACE()
  4050.  
  4051.  
  4052. Function:
  4053.      The DISKSPACE() function returns the number of bytes available on the
  4054.      default drive.
  4055.  
  4056. Syntax:
  4057.      DISKSPACE()
  4058.  
  4059. Return Value:
  4060.      NUMERIC
  4061.  
  4062. See Also:
  4063.      GETENV(), OS(), VERSION()
  4064.  
  4065. DOW()
  4066.  
  4067.  
  4068. Function:
  4069.      The DOW() function returns a number representing the day of the week.
  4070.  
  4071. Syntax
  4072.      DOW(<dexpr>)
  4073.  
  4074. Return Value:
  4075.      NUMERIC
  4076.  
  4077. Remarks:
  4078.      Returns a number representing the day of the week.  Sunday returns 1, and
  4079.      Saturday returns 7
  4080.  
  4081. Example:
  4082.      Assume the system date is 10/21/93
  4083.  
  4084. ? DOW(DATE())                                      5
  4085.  
  4086. See Also:
  4087.      CDOW(), DAY()
  4088.  
  4089.  
  4090. DTOC()
  4091.  
  4092. Function:
  4093.      The DTOC() function returns a character representation of the date
  4094. expression.
  4095.  
  4096.                                                                              63
  4097.  
  4098.  
  4099.  
  4100. Syntax:
  4101.      DTOC(<dexpr>)
  4102.  
  4103. Return Value:
  4104.      CHARACTER
  4105.  
  4106. Remarks:
  4107.      Returns a character representation of <dexpr> in the form mm/dd/yy if SET
  4108.      CENTURY is OFF, or mm/dd/ccyy if SET CENTURY is ON.
  4109.  
  4110. Example:
  4111.      Assume the system date is 10/21/93
  4112.  
  4113. ? DTOC(DATE())                                     10/21/93
  4114.  
  4115. See Also:
  4116.      CTOD(), SET CENTURY
  4117.  
  4118. EOF()
  4119.  
  4120.  
  4121. Function:
  4122.      The EOF() function indicates the end of the current database file.
  4123.  
  4124. Syntax:
  4125.      EOF()
  4126.  
  4127. Return Value:
  4128.      LOGICAL
  4129.  
  4130. Remarks:
  4131.      Returns a logical true (.T.) when record pointer is positioned after the
  4132.      last logical record of the current database file.
  4133.  
  4134. Example:
  4135.  
  4136. USE customer
  4137. GOTO BOTTOM
  4138. ? EOF()                                            .F.
  4139. SKIP 1
  4140. ? EOF()                                            .T.
  4141.  
  4142. See Also:
  4143.      BOF(), FOUND()
  4144.  
  4145.  
  4146.  
  4147.  
  4148.  
  4149.  
  4150.  
  4151.  
  4152.  
  4153.  
  4154.  
  4155.  
  4156.  
  4157.  
  4158.  
  4159.                                                                              64
  4160.  
  4161.  
  4162. ERROR()
  4163.  
  4164. Function:
  4165.      The ERROR() function returns the number corresponding to the error that
  4166.      caused an error condition.
  4167.  
  4168. Syntax:
  4169.      ERROR()
  4170.  
  4171. Return Value:
  4172.      NUMERIC
  4173.  
  4174. Remarks:
  4175.      The ERROR() function is used for runtime error handling.  In the
  4176.      procedure set by the ON ERROR command the ERROR() function can be used to
  4177.      attempt corrective action and then RETRY execution.  The return values of
  4178.      the ERROR() function are outlined in APPENDIX A.
  4179.  
  4180. Example:
  4181.      The following program will recover from the error:  File is already open.
  4182.  
  4183. ON ERROR DO recover
  4184. <commands>
  4185. USE customer
  4186. <commands>
  4187. RETURN
  4188.  
  4189. PROCEDURE recover
  4190.  
  4191. IF ERROR() =  3
  4192.   CLOSE DATABASES
  4193.   RETRY                            && attempt to re-use
  4194. ENDIF
  4195. RETURN
  4196.  
  4197. See Also:
  4198.      MESSAGE(), ON ERROR(), RETRY
  4199.  
  4200.  
  4201. EXP()
  4202.  
  4203. Function:
  4204.      The EXP() function returns the value of ex.
  4205.  
  4206. Syntax:
  4207.      EXP(<nexpr>)
  4208.  
  4209. Return Value:
  4210.      NUMERIC
  4211.  
  4212. Remarks:
  4213.      Returns the value ex where x is <nexpr>.
  4214.  
  4215. Example:
  4216.  
  4217. ? EXP(1.000)                                       2.718
  4218.  
  4219. See Also:
  4220.  
  4221.  
  4222.                                                                              65
  4223.  
  4224.  
  4225.      LOG()
  4226.  
  4227. FIELD()
  4228.  
  4229.  
  4230. Function:
  4231.      The FIELD() function returns field names from the current database file.
  4232.  
  4233. Syntax:
  4234.      FIELD(<nexpr>)
  4235.  
  4236. Return Value:
  4237.      CHARACTER
  4238.  
  4239. Remarks:
  4240.      Returns the field name corresponding to <nexpr> in  the file structure of
  4241.      the current database file.  The returned field name is in uppercase.
  4242.  
  4243. Example:
  4244.  
  4245. USE customer
  4246. ? FIELD(2)                                         LASTNAME
  4247.  
  4248. See Also:
  4249.      DBF()
  4250.  
  4251. FILE()
  4252.  
  4253.  
  4254. Function:
  4255.      The FILE() function determines the existence of  a file on the disk.
  4256.  
  4257. Syntax:
  4258.      FILE(<cexpr>)
  4259.  
  4260. Return Value:
  4261.      LOGICAL
  4262.  
  4263. Remarks:
  4264.      Returns a logical True (.T.) if the file specified by <cexpr> exists.  If
  4265.      no drive is specified the default drive is used.   FILE() will search the
  4266.      current directory first  and then  any directories  specified by  the SET
  4267.      PATH TO command.
  4268.  
  4269. Example:
  4270.       If the default drive is C and customer.dbf is on D
  4271.  
  4272. ? FILE(customer.dbf)                               .F.
  4273. ? FILE(d:customer.dbf)                             .T.
  4274.  
  4275. See Also:
  4276.      SET PATH
  4277.  
  4278.  
  4279. FLOCK()
  4280.  
  4281. Function:
  4282.      The FLOCK()  function attempts  to  lock the  current  database file  and
  4283.      returns the whether it was successful.
  4284.  
  4285.                                                                              66
  4286.  
  4287.  
  4288.  
  4289. Syntax:
  4290.      FLOCK()
  4291.  
  4292. Remarks:
  4293.      LOCK() will return True (.T.) if  dB Online was able to  lock the current
  4294.      database file.  It will return False (.F.) otherwise.   Any file that has
  4295.      been locked by another user cannot be written to.
  4296.  
  4297.      A record remains locked until  RLOCK() is issued, the file  is closed, or
  4298.      the UNLOCK command is issued.
  4299.  
  4300.      FLOCK() will re-attempt to lock  the current database based  on the value
  4301.      of SET REPROCESS TO.
  4302.  
  4303. Example:
  4304.  
  4305. IF FLOCK()
  4306.   PACK                             && must lock before PACKing
  4307. ELSE
  4308.   ? "Unable to lock file", dbf()
  4309.   RETURN
  4310. ENDIF
  4311.  
  4312. See Also:
  4313.      LOCK(), RLOCK(), SET EXCLUSIVE, SET REPROCESS, UNLOCK, USE
  4314.  
  4315. FOUND()
  4316.  
  4317.  
  4318. Function:
  4319.      The FOUND()  function returns  the success  of the  previous FIND,  SEEK,
  4320.      LOCATE, or CONTINUE command.
  4321.  
  4322. Syntax:
  4323.      FOUND()
  4324.  
  4325. Return Value:
  4326.      LOGICAL
  4327.  
  4328. Remarks:
  4329.      Returns a  logical True  (.T.) if  the  previous FIND,  SEEK, LOCATE,  or
  4330.      CONTINUE command  is  successful.   If  files  are  linked with  the  SET
  4331.      RELATION command dB Online  does an implicit  SEEK on the  slave database
  4332.      files.  FOUND() will then return  the status of the slave files.   If the
  4333.      record pointer is moved with any other commands  the result of FOUND() is
  4334.      .F.
  4335.  
  4336. See Also:
  4337.      CONTINUE, EOF(), LOCATE(), SEEK, SET RELATIOIN
  4338.  
  4339.  
  4340.  
  4341.  
  4342.  
  4343.  
  4344.  
  4345.  
  4346.  
  4347.  
  4348.                                                                              67
  4349.  
  4350.  
  4351. GETENV()
  4352.  
  4353. Function:
  4354.      The GETENV()  function  returns  the  value  of an  environmental  system
  4355. variable.
  4356.  
  4357. Syntax:
  4358.      GETENV(<cexpr>)
  4359.  
  4360. Return Value:
  4361.      CHARACTER
  4362.  
  4363. Remarks:
  4364.      Returns the value of the DOS system variable specified by <cexpr> such as
  4365.      PATH or COMSPEC.   If the character expression  is not found,   dB Online
  4366.      returns a null string.
  4367.  
  4368. Example:
  4369.  
  4370. ? GETENV("COMSPEC")                                C:\COMMAND.COM
  4371. ? GETENV("PATH")                                   C:\DOS;C:\BIN
  4372.  
  4373. See Also:
  4374.      DISKSPACE, OS(), VERSION()
  4375.  
  4376.  
  4377. IIF()
  4378.  
  4379. Function:
  4380.      The IIF() function is a shortcut to the IF...ENDIF structure.  It returns
  4381.      one of two values based on a logical expression.
  4382.  
  4383. Syntax:
  4384.      IIF(<lexpr>,<expr1>,<expr2>)
  4385.  
  4386. Return Value:
  4387.      <expr1> or <expr2>
  4388.  
  4389. Remarks:
  4390.      Returns the value of <expr1> if <lexpr> is  Logical True (.T.), otherwise
  4391.      it returns the value of <expr2>.
  4392.  
  4393. Example:
  4394.  
  4395. lastname = "Smith"
  4396. ? IIF(sex = 'M',"Mr. ","Ms. ") + lastname
  4397.  
  4398. See Also:
  4399.      IF...ENDIF, DO CASE
  4400.  
  4401.  
  4402. INKEY()
  4403.  
  4404. Function:
  4405.      The INKEY() function  returns a  value representing  the most  recent key
  4406.      pressed by either the remote or local terminals.  It  does not wait for a
  4407.      keypress.
  4408.  
  4409.  
  4410.  
  4411.                                                                              68
  4412.  
  4413.  
  4414. Syntax:
  4415.      INKEY()
  4416.  
  4417. Return Value:
  4418.      NUMERIC
  4419.  
  4420. Remarks:
  4421.      Returns a value in the range of 0 to 255  corresponding to a value in the
  4422.      IBM  Extended  Character.    If  there  are  several  characters  in  the
  4423.      type-ahead buffer the  first character is  returned and cleared  from the
  4424.      buffer.
  4425.  
  4426.      INKEY() returns zero if no key is pressed  and the control-key equivalent
  4427.      of cursor and extended keys.   The return values of  INKEY are identified
  4428.      in the following table:
  4429.  
  4430.           Cursor Key    Alternative Keys   INKEY() return value
  4431.           Right         Ctrl-D                                     4
  4432.  
  4433.           Left          Ctrl-S                                    19
  4434.           Up            Ctrl-E                                     5
  4435.           Down          Ctrl-X                                    24
  4436.  
  4437.           Ctrl-Right    Ctrl-B                                     2
  4438.           Ctrl-Left     Ctrl-Z                                    26
  4439.  
  4440.           Ins           Ctrl-V                                    22
  4441.           Delete        Ctrl-G                                     7
  4442.           Home          Ctrl-A                                     1
  4443.  
  4444.           End           Ctrl-F                                     6
  4445.           PgUp          Ctrl-R                                    18
  4446.           PgDn          Ctrl-C                                     3
  4447.  
  4448.           Ctrl-Home     Ctrl-]                                    29
  4449.           Ctrl-End      Ctrl-W                                    23
  4450.           Esc                                                     27
  4451.  
  4452.           Ctrl-PgUp     Ctrl-_                                    31
  4453.           Ctrl-PgDn     Ctrl-]                                    30
  4454.  
  4455.  
  4456. Example:
  4457.  
  4458. ? "Press any key to continue"
  4459. DO WHILE INKEY() =0
  4460.   @ 1,72 SAY TIME()
  4461. ENDDO
  4462.  
  4463. See Also:
  4464.      CHR(), LASTKEY(), WAIT
  4465.  
  4466. INT()
  4467.  
  4468.  
  4469. Function:
  4470.      The INT() function return the integer portion of a numeric argument
  4471.  
  4472. Syntax:
  4473.  
  4474.                                                                              69
  4475.  
  4476.  
  4477.      INT(<nexpr>)
  4478.  
  4479. Return Value:
  4480.      NUMERIC
  4481.  
  4482. Remarks:
  4483.      Returns the integer portion of <nexpr>.   All digits to the  right of the
  4484.      decimal point are discarded.
  4485.  
  4486. Example:
  4487. ? INT(23.55)                                       23
  4488. ? INT(-5.5)                                        -5
  4489.  
  4490. ISALPHA()
  4491.  
  4492.  
  4493. Function:
  4494.      The ISALPHA function returns a  logical True (.T.) if  a character string
  4495.      begins with an alpha character.
  4496.  
  4497. Syntax:
  4498.      ISALPHA(<cexpr>)
  4499.  
  4500. Return Value:
  4501.      LOGICAL
  4502.  
  4503. Remarks:
  4504.      Returns a logical  True (.T.)  if the  first character  in <cexpr>  is an
  4505.      upper or lower case letter between a and z.
  4506.  
  4507. Example:
  4508.  
  4509. ? ISALPHA("HELLO")                                 .T.
  4510. ? ISALPHA("123 Main St.")                          .F.
  4511.  
  4512. See Also:
  4513.      ISLOWER(), ISUPPER()
  4514.  
  4515. ISCOLOR()
  4516.  
  4517.  
  4518. Function:
  4519.      The ISCOLOR()  function determines  whether the  user has  selected color
  4520.      operation.
  4521.  
  4522. Syntax:
  4523.      ISCOLOR()
  4524.  
  4525. Return Value:
  4526.      LOGICAL
  4527.  
  4528. Remarks:
  4529.      This information  is provided  by a  BBS drop  file.   See the  ISCOLOR()
  4530.      command in the BBS Information Functions section for further details.
  4531.  
  4532.      ISCOLOR() a logical True (.T.) if the user has selected color operation.
  4533.  
  4534. Example:
  4535.      To change default black and white colors if user is in color mode:
  4536.  
  4537.                                                                              70
  4538.  
  4539.  
  4540.  
  4541. IF ISCOLOR()
  4542.   SET COLOR TO W+/B,N/BG
  4543. ENDIF
  4544.  
  4545. See Also:
  4546.      SET COLOR
  4547.  
  4548. ISLOWER()
  4549.  
  4550.  
  4551. Function:
  4552.      The ISLOWER()  function returns  a logical  True (.T.)  if the  character
  4553.      expression begins with a lowercase letter.
  4554.  
  4555. Syntax:
  4556.      ISLOWER(<cexpr>)
  4557.  
  4558. Return Value:
  4559.      LOGICAL
  4560.  
  4561. Example:
  4562.  
  4563. ? ISLOWER("Hello")                                 .F.
  4564. ? ISLOWER("hello")                                 .T.
  4565. ? ISLOWER("123 Main St.")                          .F.
  4566.  
  4567. See Also:
  4568.      ISALPHA(), ISUPPER()
  4569.  
  4570. ISUPPER()
  4571.  
  4572.  
  4573. Function:
  4574.      The ISUPPER()  function returns  a logical  True (.T.)  if the  character
  4575.      expression begins with a uppercase letter.
  4576.  
  4577. Syntax:
  4578.      ISUPPER(<cexpr>)
  4579.  
  4580. Return Value:
  4581.      LOGICAL
  4582.  
  4583. Example:
  4584.  
  4585. ? ISUPPER("Hello")                                 .T.
  4586. ? ISUPPER("hello")                                 .F.
  4587. ? ISUPPER("123 Main St.")                          .F.
  4588.  
  4589. See Also:
  4590.      ISALPHA(), ISLOWER()
  4591.  
  4592.  
  4593. LASTKEY()
  4594.  
  4595. Function:
  4596.      The LASTKEY() function returns the value of the  last key pressed to exit
  4597.      a full screen READ command.
  4598.  
  4599.  
  4600.                                                                              71
  4601.  
  4602.  
  4603. Syntax:
  4604.      LASTKEY()
  4605.  
  4606. Return Value:
  4607.      NUMERIC
  4608.  
  4609. Remarks:
  4610.      The return values of LASTKEY correspond to the INKEY() values.
  4611.  
  4612. Example:
  4613.  
  4614. @ 2,2 SAY "NAME" GET NAME
  4615. <commands>
  4616. READ
  4617. IF LASTKEY() = 27
  4618.   QUIT
  4619. ENDIF
  4620.  
  4621. See Also:
  4622.      INKEY()
  4623.  
  4624. LEFT()
  4625.  
  4626.  
  4627. Function:
  4628.      The LEFT() function returns a number of characters  from the beginning of
  4629.      the specified character expression.
  4630.  
  4631. Syntax:
  4632.      LEFT(<cexpr>,<nexpr>)
  4633.  
  4634. Return Value:
  4635.      CHARACTER
  4636.  
  4637. Remarks:
  4638.      Returns the leftmost <nexpr> characters  in <cexpr>.  If  <nexpr> is less
  4639.      than or equal to  zero, dB Online returns  a null string.   If <nexpr> is
  4640.      greater than the length of <cexpr>, dB Online returns the entire string.
  4641.  
  4642. Example:
  4643.  
  4644. ? LEFT([Hello There],5)                            Hello
  4645.  
  4646. See Also:
  4647.      AT(), LTRIM(), RIGHT(), SUBSTR(), TRIM()
  4648.  
  4649. LEN()
  4650.  
  4651.  
  4652. Function:
  4653.      The LEN() function returns the length of a character string.
  4654.  
  4655. Syntax:
  4656.      LEN(<cexpr>)
  4657.  
  4658. Return Value:
  4659.      NUMERIC
  4660.  
  4661. Remarks:
  4662.  
  4663.                                                                              72
  4664.  
  4665.  
  4666.      Returns the length of  <cexpr>.  If <cexpr>  is a null string,  dB Online
  4667. returns zero.
  4668.  
  4669. Example:
  4670.  
  4671. ? LEN("Good Morning")                              12
  4672.  
  4673. See Also:
  4674.      TRIM()
  4675.  
  4676. LOCK()
  4677.  
  4678.  
  4679. Function:
  4680.      The LOCK() function attempts to  lock the current record  and returns the
  4681.      whether it was successful.  LOCK() is identical to RLOCK().  Please refer
  4682.      to RLOCK() in this section.
  4683.  
  4684. Syntax:
  4685.      LOCK() | RLOCK()
  4686.  
  4687. See Also:
  4688.      FLOCK(), RLOCK(), SET EXCLUSIVE, SET REPROCESS, UNLOCK, USE
  4689.  
  4690. LOG()
  4691.  
  4692.  
  4693. Function:
  4694.      The LOG() function returns the natural logarithm of a numeric expression.
  4695.  
  4696. Syntax:
  4697.      LOG(<nexpr>)
  4698.  
  4699. Return Value:
  4700.      NUMERIC
  4701.  
  4702. Remarks:
  4703.      Returns the natural logarithm of  <nexpr>.  <nexpr> must  be greater than
  4704. zero.
  4705.  
  4706. Example:
  4707.  
  4708. ? LOG(2.71828)                                     1.00000
  4709.  
  4710. See Also:
  4711.      EXP()
  4712.  
  4713.  
  4714. LOWER()
  4715.  
  4716. Function:
  4717.      The LOWER() function converts a character expression to lower case.
  4718.  
  4719. Syntax:
  4720.      LOWER(<cexpr>)
  4721.  
  4722. Return Value:
  4723.      CHARACTER:
  4724.  
  4725.  
  4726.                                                                              73
  4727.  
  4728.  
  4729. Remarks:
  4730.      Returns a string in which  all uppercase characters in  <cexpr> have been
  4731.      converted to lowercase.
  4732.  
  4733. Example:
  4734.  
  4735. ? LOWER("Hello")                                   hello
  4736.  
  4737. See Also:
  4738.      ISALPHA(), ISLOWER(), ISUPPER(), UPPER()
  4739.  
  4740. LTRIM()
  4741.  
  4742.  
  4743. Function:
  4744.      The LTRIM() function removes leading blanks from a character expression.
  4745.  
  4746. Syntax:
  4747.      LTRIM(<cexpr>)
  4748.  
  4749. Return Value:
  4750.      <cexpr>
  4751.  
  4752. Example:
  4753. ? STR(12.45)                                               12.45
  4754. ? LTRIM(STR(12.45))                                12.45
  4755.  
  4756. See Also:
  4757.      LEFT(), RIGHT(), RTRIM(), STR(), SUBSTR(), TRIM()
  4758.  
  4759. LUPDATE()
  4760.  
  4761.  
  4762. Function:
  4763.      The LUPDATE() function  returns the last  date the current  database file
  4764. was updated.
  4765.  
  4766. Syntax:
  4767.      LUPDATE()
  4768.  
  4769. Return Value:
  4770.      DATE
  4771.  
  4772. Example:
  4773.      Assume the system date is 10/21/93
  4774.  
  4775. USE customer
  4776. ?LUPDATE()                                         9/15/93
  4777. PACK
  4778. ?LUPDATE()                                         10/21/93
  4779.  
  4780. See Also:
  4781.      DBF()
  4782.  
  4783.  
  4784. MAX()
  4785.  
  4786. Function:
  4787.      The MAX() function returns the largest of two numeric or date functions.
  4788.  
  4789.                                                                              74
  4790.  
  4791.  
  4792.  
  4793. Syntax:
  4794.      MAX(<nexpr1>|<dexpr1>,<nexpr2>|<dexpr2>)
  4795.  
  4796. Return Value:
  4797.      NUMERIC|DATE
  4798.  
  4799. Remarks:
  4800.      Returns the largest of the two values.   Both <expr1> and <expr2> must be
  4801.      either NUMERIC or DATE types.
  4802.  
  4803. Example:
  4804.  
  4805. ? MAX(55,102)                                      102
  4806.  
  4807. See Also:
  4808.      MIN()
  4809.  
  4810. MDX()
  4811.  
  4812.  
  4813. Function:
  4814.      The MDX() function returns the filename for the active index files in a
  4815.      work area.
  4816.  
  4817. Syntax:
  4818.      MDX(<nexpr1>[,<nexpr2>|<alias>])
  4819.  
  4820. Return Value:
  4821.      CHARACTER
  4822.  
  4823. Remarks:
  4824.      Returns the filename of an open .mdx file in a work area.  <nexpr1> is
  4825.      the .mdx file position in the index file list specified by the SET INDEX
  4826.      TO <file list>, or USE INDEX <file list> commands.  The optional second
  4827.      parameter returns .mdx files for other work areas.
  4828.  
  4829. Example:
  4830.  
  4831. USE customer INDEX name.mdx, phone.mdx
  4832. ? MDX(1)                                           c:name.mdx
  4833. ? MDX(2)                                           c:phone.mdx
  4834.  
  4835. See Also:
  4836.      CDX(), DBF(), FIELD(), LUPDATE(), NDX(), SET INDEX, SET ORDER
  4837.  
  4838. MESSAGE()
  4839.  
  4840.  
  4841. Function:
  4842.      The MESSAGE()  function returns  the  message corresponding  to an  error
  4843. condition.
  4844.  
  4845. Syntax:
  4846.      MESSAGE()
  4847.  
  4848. Return Value:
  4849.      CHARACTER
  4850.  
  4851.  
  4852.                                                                              75
  4853.  
  4854.  
  4855. Remarks:
  4856.      Returns the character message during a runtime error handling procedure.
  4857.  
  4858. Example:
  4859.  
  4860. ON ERROR DO recover
  4861. <commands>
  4862.  
  4863. PROCEDURE recover
  4864.   ?"dB Online has encountered a run time error"
  4865.   ? MESSAGE()
  4866.   ? "Now exiting"
  4867.   QUIT
  4868. RETURN
  4869.  
  4870. See Also:
  4871.      ERROR()
  4872.  
  4873. MIN()
  4874.  
  4875.  
  4876. Function:
  4877.      The MIN() function returns the smaller of two numeric or date functions.
  4878.  
  4879. Syntax:
  4880.      MIN(<nexpr1>|<dexpr1>,<nexpr2>|<dexpr2>)
  4881.  
  4882. Return Value:
  4883.      NUMERIC|DATE
  4884.  
  4885. Remarks:
  4886.      Returns the smaller of the two values.   Both <expr1> and <expr2> must be
  4887.      either NUMERIC or DATE types.
  4888.  
  4889. Example:
  4890.  
  4891. ? MIN(55,102)                                      55
  4892.  
  4893. See Also:
  4894.      MAX()
  4895.  
  4896. MOD()
  4897.  
  4898.  
  4899. Function:
  4900.      The MOD() function returns the remainder from a division of two numbers.
  4901.  
  4902. Syntax:
  4903.      MOD(<nexpr1>,<nexpr2>)
  4904.  
  4905. Return Value:
  4906.      NUMERIC
  4907.  
  4908. Remarks:
  4909.      Returns the  modulus,  which  is the  remainder  of  <nexpr1> divided  by
  4910. <nexpr2>
  4911.  
  4912. Example:
  4913.  
  4914.  
  4915.                                                                              76
  4916.  
  4917.  
  4918. ? MOD(10,8)                                        2
  4919. ? MOD(0,60)                                        0
  4920.  
  4921. MONTH()
  4922.  
  4923.  
  4924. Function:
  4925.      The MONTH() function returns a number representing the  month from a date
  4926.      expression.
  4927.  
  4928. Syntax:
  4929.      MONTH(<dexpr>)
  4930.  
  4931. Return Value:
  4932.      NUMERIC
  4933.  
  4934. Remarks:
  4935.      Returns a value between 1 and 12 corresponding to January to December.
  4936.  
  4937. Example:
  4938.      Assume the system date is 10/21/93
  4939.  
  4940. ? MONTH(DATE())                                    10
  4941.  
  4942. See Also:
  4943.      CMONTH(), DAY(), YEAR()
  4944.  
  4945. NDX()
  4946.  
  4947.  
  4948. Function:
  4949.      The NDX() function returns the filename for the active index files in a
  4950.      work area.
  4951.  
  4952. Syntax:
  4953.      NDX(<nexpr1>[,<nexpr2>|<alias>])
  4954.  
  4955. Return Value:
  4956.      CHARACTER
  4957.  
  4958. Remarks:
  4959.      Returns the filename of an open .ndx file in a work area.  <nexpr1> is
  4960.      the .ndx file position in the index file list specified by the SET INDEX
  4961.      TO <file list>, or USE INDEX <file list> commands.  The optional second
  4962.      parameter returns .ndx files for other work areas.
  4963.  
  4964. Example:
  4965.  
  4966. USE customer INDEX name.ndx, phone.ndx
  4967. ? NDX(1)                                           c:name.ndx
  4968. ? NDX(2)                                           c:phone.ndx
  4969.  
  4970. See Also:
  4971.      CDX(), DBF(), LUPDATE(), SET INDEX, SET ORDER
  4972.  
  4973.  
  4974. OS()
  4975.  
  4976. Function:
  4977.  
  4978.                                                                              77
  4979.  
  4980.  
  4981.      The OS() function returns the name of the operating system under which dB
  4982.      Online is running.
  4983.  
  4984. Syntax:
  4985.      OS()
  4986.  
  4987. Return Value:
  4988.      CHARACTER
  4989.  
  4990. Remarks:
  4991.      Returns a character  value of the  operating system.   As dB  Online only
  4992.      operates in DOS environments, OS() returns the DOS version.
  4993.  
  4994. Example:
  4995.  
  4996. ? OS()                                             DOS 5.0
  4997.  
  4998. See Also:
  4999.      DISKSPACE(), GETENV(), VERSION()
  5000.  
  5001. READKEY()
  5002.  
  5003.  
  5004. Function:
  5005.      The READKEY() function  returns a value  representing the key  pressed to
  5006.      exit a full screen read statement.  READKEY()  also indicates whether any
  5007.      data was changed.
  5008.  
  5009. Syntax:
  5010.      READKEY()
  5011.  
  5012. Return Value:
  5013.      NUMERIC
  5014.  
  5015. Remarks:
  5016.      The READKEY() return values are  identified in the table below.   If none
  5017.      of the data had  been changed, the return  value is between zero  and 15.
  5018.      If any of the data had been changed the return value increases by 256.
  5019.  
  5020.             Key pressed   READKEY()     READKEY() Meaning
  5021.                           No changes    Changes
  5022.                    Ctrl-S
  5023.             Left ,               0          256   Backward one
  5024.                , Ctrl-H
  5025.             BS                                    character
  5026.  
  5027.             Right , Ctrl-D       1          257   Forward one
  5028.                                                   character
  5029.             Up , Ctrl-E          4          260   Backward one
  5030.                                                   field
  5031.  
  5032.             Down , Ctrl-X        5          261   Forward one
  5033.                                                   field
  5034.             PgUp , Ctrl-R        6          262   Backward one
  5035.                                                   screen
  5036.             PgDn , Ctrl-C        7          263   Forward one
  5037.                                                   screen
  5038.  
  5039.             Esc , Ctrl-Q        12          ---   Terminate
  5040.                                                   without save
  5041.  
  5042.  
  5043.                                                                              78
  5044.  
  5045.  
  5046.             Ctrl-End            13          270   Terminate with
  5047.             Ctrl-W                                save
  5048.             Enter , Tab         15          271   Completed last
  5049.                                                   field
  5050.  
  5051.  
  5052.  
  5053. Example:
  5054.      To determine if  the contents of  a memory  variable were altered  and to
  5055.      REPLACE a field if changes were made.
  5056.  
  5057. @ 2,2 SAY "NAME" GET mname
  5058. READ
  5059. IF READKEY() >=256                 && if data changed
  5060.   REPLACE name WITH mname
  5061. ENDIF
  5062.  
  5063. See Also:
  5064.      INKEY(), READ
  5065.  
  5066.  
  5067. RECCOUNT()
  5068.  
  5069. Function:
  5070.      The RECCOUNT() function  returns the number  of records in  the currently
  5071.      selected database.
  5072.  
  5073. Syntax:
  5074.      RECCOUNT()
  5075.  
  5076.  
  5077. Return Value:
  5078.      NUMERIC
  5079.  
  5080. Example:
  5081.  
  5082. USE clients.dbf
  5083. ? RECCOUNT()                                       49
  5084.  
  5085. See Also:
  5086.      DBF(), DISKSPACE(), RECNO(), RECSIZE()
  5087.  
  5088.  
  5089. RECNO()
  5090.  
  5091. Function:
  5092.      The RECNO() function  returns the current  record number of  the selected
  5093. database.
  5094.  
  5095. Syntax:
  5096.      RECNO()
  5097.  
  5098. Return Value:
  5099.      NUMERIC
  5100.  
  5101. Example:
  5102.  
  5103. USE clients.dbf
  5104. ? RECNO()                                          1
  5105.  
  5106.                                                                              79
  5107.  
  5108.  
  5109. SKIP
  5110. ? RECNO()                                          2
  5111. GO BOTTOM
  5112. ? RECNO()                                          49
  5113.  
  5114. See Also:
  5115.      GOTO, RECCOUNT(), SKIP
  5116.  
  5117. RECSIZE()
  5118.  
  5119.  
  5120. Function:
  5121.      The RECSIZE() functions  returns the  size of a  record in  the currently
  5122.      selected database file.
  5123.  
  5124. Syntax:
  5125.      RECSIZE()
  5126.  
  5127. Return Value:
  5128.      NUMERIC
  5129.  
  5130.  
  5131. Example:
  5132.  
  5133. USE customer.dbf
  5134. ? RECSIZE()                                        43
  5135.  
  5136. See Also:
  5137.      DBF(), DISKSPACE(), LUPDATE(),  RECCOUNT()
  5138.  
  5139. REPLICATE()
  5140.  
  5141.  
  5142. Function:
  5143.      The REPLICATE()  function  repeats  a  character expression  a  specified
  5144.      number of times.
  5145.  
  5146. Syntax:
  5147.      REPLICATE(<cexpr>,<nexpr>)
  5148.  
  5149. Return Value:
  5150.      CHARACTER
  5151.  
  5152. Remarks:
  5153.      Returns  <cexpr>  repeated  <nexpr>  times.     The  resulting  character
  5154.      expression must not exceed 254 characters.
  5155.  
  5156. Example:
  5157.      REPLICATE can be used to create bar graphs
  5158.  
  5159. percent1 = 30
  5160. percent2 = 60
  5161. ? percent1, REPLICATE('*',percent1/10)
  5162. 30 ***
  5163. ? percent2, REPILCATE('*',percent2/10)
  5164. 60 ******
  5165.  
  5166. See Also:
  5167.      SPACE()
  5168.  
  5169.                                                                              80
  5170.  
  5171.  
  5172. RIGHT()
  5173.  
  5174. Function:
  5175.      The RIGHT() function  returns a specified  number of characters  from the
  5176.      end of a character expression.
  5177.  
  5178. Syntax:
  5179.      RIGHT(<cexpr>,<nexpr>)
  5180.  
  5181. Return Value:
  5182.      CHARACTER
  5183.  
  5184. Remarks
  5185.      Return the last <nexpr> characters  of <cexpr>.  If <nexpr>  is less than
  5186.      or equal to zero, then a null string is returned.   If <nexpr> is greater
  5187.      than the length of <cexpr> then the entire string is returned.
  5188.  
  5189. Example:
  5190.  
  5191. ? RIGHT('Hello Bob',3)                             Bob
  5192.  
  5193. See Also:
  5194.      LEFT(), LTRIM(), SUBSTR(), TRIM()
  5195.  
  5196.  
  5197. RLOCK()
  5198.  
  5199. Function:
  5200.      The RLOCK() function attempts to lock the current  record and returns the
  5201.      whether it was successful.
  5202.  
  5203. Syntax:
  5204.      RLOCK() | LOCK()
  5205.  
  5206. Remarks:
  5207.      RLOCK() will return True (.T.) if dB Online was  able to lock the current
  5208.      record.  It will return False (.F.) otherwise.   Any record that has been
  5209.      locked by another user cannot be written to.
  5210.  
  5211.      A record remains locked until  the the record pointer is  moved, the file
  5212.      is closed, or the UNLOCK command is issued.
  5213.  
  5214.      RLOCK() will re-attempt to lock the current record  based on the value of
  5215.      SET REPROCESS TO.
  5216.  
  5217. Example:
  5218.  
  5219. IF RLOCK()
  5220.   DO editproc                      && edit the record
  5221. ELSE
  5222.   CLEAR
  5223.   ? "Unable to lock record"
  5224.   RETURN
  5225. ENDIF
  5226.  
  5227. See Also:
  5228.      FLOCK(), LOCK(), SET EXCLUSIVE, SET REPROCESS, UNLOCK, USE
  5229.  
  5230.  
  5231.  
  5232.                                                                              81
  5233.  
  5234.  
  5235. ROUND()
  5236.  
  5237. Function:
  5238.      The ROUND() function rounds off numbers to a  specified number of decimal
  5239. places.
  5240.  
  5241. Syntax:
  5242.      ROUND(<nexpr1>,<nexpr2>)
  5243.  
  5244. Return value:
  5245.      NUMERIC
  5246.  
  5247. Remarks:
  5248.      Returns <nexpr1> rounded off to <nexpr2> decimal places.   If <nexpr2> is
  5249.      negative,  Round() returns a rounded whole number.
  5250.  
  5251. Example:
  5252.  
  5253. ? ROUND(123.4567,2)                                      123.46
  5254. ? ROUND(123.4567,0)                                      123
  5255. ? ROUND(123.4567,-1)                                     120
  5256.  
  5257. See Also:
  5258.      INT()
  5259.  
  5260.  
  5261. ROW()
  5262.  
  5263. Function:
  5264.      The ROW() function returns the row number of  the current cursor position
  5265.      on the local and remote screens.
  5266.  
  5267. Syntax:
  5268.      ROW()
  5269.  
  5270.  
  5271. Return value:
  5272.      NUMERIC
  5273.  
  5274. Remarks:
  5275.      Returns the current row number between 0 and 24.
  5276.  
  5277. Example:
  5278.  
  5279. CLEAR
  5280. ? ROW()                                               1
  5281. ? ROW()                                               2
  5282.  
  5283. See Also:
  5284.      @...SAY...GET, ROW()
  5285.  
  5286.  
  5287. RTRIM()
  5288.  
  5289. Function:
  5290.      The RTRIM() function removes trailing blanks from a character expression.
  5291.  
  5292. Syntax:
  5293.  
  5294.  
  5295.                                                                              82
  5296.  
  5297.  
  5298.      RTRIM(<cexpr>)
  5299.  
  5300. Return Value:
  5301.      <cexpr>
  5302.  
  5303. Remarks:
  5304.      The RTRIM() function is identical to the TRIM() function.
  5305.  
  5306. Example:
  5307.  
  5308. title = "Mr.     "
  5309. name = "Jones"
  5310. ? title + name                                     Mr.     Jones
  5311. ? RTRIM(title)+' '+name                            Mr. Jones
  5312.  
  5313. See Also:
  5314.      LEFT(), LTRIM(), RIGHT(), TRIM()
  5315.  
  5316. SPACE()
  5317.  
  5318.  
  5319. Function:
  5320.      The SPACE() function generates a character  string containing a specified
  5321.      number of spaces.
  5322.  
  5323. Syntax:
  5324.      SPACE(<nexpr>)
  5325.  
  5326. Return value:
  5327.      CHARACTER
  5328.  
  5329. Remarks:
  5330.      The range of <nexpr> is from 0 to 254
  5331.  
  5332. Example:
  5333.  
  5334. ? '*' + SPACE(10) + '*'                            *          *
  5335.  
  5336. See Also:
  5337.      REPLICATE()
  5338.  
  5339. SQRT()
  5340.  
  5341.  
  5342. Function:
  5343.      The SQRT()  function returns  the  square root  of  a specified  positive
  5344. numeric argument.
  5345.  
  5346. Syntax:
  5347.      SQRT(<nexpr>)
  5348.  
  5349. Return value:
  5350.      NUMERIC
  5351.  
  5352. Example:
  5353.  
  5354. ? SQRT(4)                                             2
  5355. ? SQRT(2)                                             1.4
  5356. ? SQRT(2.0000)                                        1.414
  5357.  
  5358.                                                                              83
  5359.  
  5360.  
  5361. STR()
  5362.  
  5363. Function:
  5364.      The STR() function converts a number into a character string
  5365.  
  5366. Syntax:
  5367.      STR(<nexpr1>[,<nexpr2>][,<nexpr3>])
  5368.  
  5369. Return value:
  5370.      CHARACTER
  5371.  
  5372.  
  5373. Remarks:
  5374.      Returns a character representation of <nexpr1>.  The  total length of the
  5375.      string is specified by <nexpr2>.  The number of decimals in the string is
  5376.      specified by <nexpr3>.  If <nexpr2> is not specified the string length is
  5377.      10.  If <nexpr3> is not specified the number is truncated to an integer.
  5378.  
  5379.      The length includes the  decimal point, minus  sign and any numbers.   If
  5380.      the number specified   is  too large to  fit into  the length,  dB Online
  5381.      returns asterisks in the string.
  5382.  
  5383. Example:
  5384. ? STR(10.54,5,2)                                   10.54
  5385. ? STR(10.54)                                               10
  5386. ? STR(1459,3,0)                                    ***
  5387.  
  5388. See Also:
  5389.      SUBSTR(), VAL()
  5390.  
  5391.  
  5392. STUFF()
  5393.  
  5394. Function:
  5395.      The STUFF()  function  replaces  a portion  of  a  character string  with
  5396.      another character string.
  5397.  
  5398. Syntax:
  5399.      STUFF(<cexpr1>,<nexpr1>,<nexpr2>,<cexpr2>)
  5400.  
  5401. Return value:
  5402.      CHARACTER
  5403.  
  5404. Remarks:
  5405.      Character expression <cexpr1>  is the  string to  be altered.   Character
  5406.      expression <cexpr2> is to be inserted into <cexpr1>.
  5407.  
  5408.      The insertion takes place at the position specified by <nexpr1>.  At this
  5409.      position <nexpr2> characters are removed from  <cexpr1> and then <cexpr2>
  5410.      is inserted.
  5411.  
  5412. Example:
  5413.  
  5414. ? STUFF('abc',2,1,'xyz')                           axyzc
  5415. ? STUFF('abc',2,1,'')                              ac
  5416. ? STUFF('abc',2,0,'xyz')                           axyzbc
  5417.  
  5418. See Also:
  5419.  
  5420.  
  5421.                                                                              84
  5422.  
  5423.  
  5424.      LEFT(), RIGHT(), SUBSTR()
  5425.  
  5426. SUBSTR()
  5427.  
  5428.  
  5429. Function:
  5430.      The SUBSTR() function  extracts a specified  number of characters  from a
  5431.      character string.
  5432.  
  5433. Syntax:
  5434.      SUBSTR(<cexpr>,<nexpr1>[,<nexpr2>])
  5435.  
  5436. Return value:
  5437.      CHARACTER:
  5438.  
  5439. Remarks:
  5440.      Returns the  next  <nexpr2>  characters  of   <cexpr>  beginning  at  the
  5441.      <nexpr1> position.  If <nexpr2>  is not specified, dB  Online returns the
  5442.      remainder of <cexpr>
  5443.  
  5444. Example:
  5445.  
  5446. ? SUBSTR("Press any key",7,3)                      any
  5447.  
  5448. See Also:
  5449.      AT(), LEFT(), RIGHT(), STR(), STUFF()
  5450.  
  5451. TAG()
  5452.  
  5453.  
  5454. Function:
  5455.      The TAG()  function  returns  the TAG  names  in  the currently  selected
  5456. database.
  5457.  
  5458. Syntax:
  5459.      TAG(<nexpr>[,<nexpr1>|<alias>])
  5460.  
  5461. Return value:
  5462.      CHARACTER:
  5463.  
  5464. Remarks:
  5465.      Returns the name of an index file (.ndx, .ntx) or a tag name (.cdx, .mdx)
  5466.      of the  currently selected  database.   In  dBASE III+    and Clipper       file
  5467.      formats, <nexpr1> identifies the index file in  the position as specified
  5468.      in the SET INDEX TO, or  USE INDEX command.  In dBASE  IV and FoxPro    file
  5469.      formats, <nexpr1> identifies the tag number of  all opened multiple index
  5470.      files.  
  5471.  
  5472.      The second parameter is used to identify tags in other work areas.
  5473.  
  5474. Example:
  5475.      To identify the second tag of cust.mdx
  5476.  
  5477. USE customer.dbf INDEX cust.mdx
  5478. ? TAG(2)                                           PHONE
  5479.  
  5480. See Also:
  5481.      CDX(), DBF(), MDX(), NDX(), SET INDEX, SET ORDER, USE
  5482.  
  5483.  
  5484.                                                                              85
  5485.  
  5486.  
  5487. TIME()
  5488.  
  5489. Function:
  5490.      The TIME() function return the current system time.
  5491.  
  5492. Syntax:
  5493.      TIME()
  5494.  
  5495. Return Value:
  5496.      CHARACTER
  5497.  
  5498. Remarks:
  5499.      Returns the current system time in the format hh:mm:ss
  5500.  
  5501. Example:
  5502.  
  5503. ? TIME()                                           12:36:55
  5504.  
  5505. See Also:
  5506.      DATE()
  5507.  
  5508.  
  5509. TRANSFORM()
  5510.  
  5511. Function:
  5512.      The TRANSFORM() function allows PICTURE formatting of data without using
  5513.      the @...SAY command.
  5514.  
  5515. Syntax:
  5516.      TRANSORM(<expr>,<cexpr>)
  5517.  
  5518. Return value:
  5519.      CHARACTER
  5520.  
  5521. Remarks:
  5522.      Returns the data in <expr> in the format specified by the PICTURE  format
  5523.      <cexpr>.  <expr> can be any of the four data types:  NUMERIC, CHARACTER,
  5524.      LOGICAL, DATE.  For information about PICTURE formats, refer to the @
  5525.      command.
  5526.  
  5527. Example:
  5528.  
  5529. ? TRANSFORM('john','!XXX')                         John
  5530. ? TRANSFORM(4123.5,'999,999.99')                      4,123.50
  5531.  
  5532. See Also:
  5533.      @...SAY...GET
  5534.  
  5535.  
  5536. TRIM()
  5537.  
  5538. Function:
  5539.      The TRIM() function is identical to the RTRIM() function.  Please refer
  5540.      to RTRIM() in this section.
  5541.  
  5542. Syntax:
  5543.      TRIM(<cexpr>)
  5544.  
  5545.  
  5546.  
  5547.                                                                              86
  5548.  
  5549.  
  5550. Return Value:
  5551.      CHARACTER
  5552.  
  5553. See Also:
  5554.      LTRIM(), RTRIM()
  5555.  
  5556. UPPER()
  5557.  
  5558.  
  5559. Function:
  5560.      The UPPER() function converts a character expression to upper case.
  5561.  
  5562. Syntax:
  5563.      UPPER(<cexpr>)
  5564.  
  5565. Return Value:
  5566.      CHARACTER:
  5567.  
  5568. Remarks:
  5569.      Returns a string in which  all lowercase characters in  <cexpr> have been
  5570.      converted to uppercase.
  5571.  
  5572. Example:
  5573.  
  5574. ? UPPER("Hello")                                   HELLO
  5575.  
  5576. See Also:
  5577.      LOWER()
  5578.  
  5579. VAL()
  5580.  
  5581.  
  5582. Function:
  5583.      The VAL() function converts a character representation of a number into a
  5584.      numeric expression.
  5585.  
  5586. Syntax:
  5587.      VAL(<cexpr>)
  5588.  
  5589. Return Value:
  5590.      NUMERIC
  5591.  
  5592. Remarks:
  5593.      Returns the value of <cexpr>.  Any leading blanks are ignored in <cexpr>.
  5594.      Once numeric digits are found,  VAL() proceeds left to right  until a non
  5595.      numeric character  is  encountered.   If  <cexpr>  is non-numeric,  VAL()
  5596.      returns zero.  The decimal  portion of the returned  number is determined
  5597.      by SET DECIMALS.
  5598.  
  5599. Example:
  5600. ? VAL("   555")                                    555.00
  5601. ? VAL("Hello")                                     0.00
  5602.  
  5603. See Also:
  5604.      SET DECIMALS, STR() 
  5605.  
  5606.  
  5607. VERSION()
  5608.  
  5609.  
  5610.                                                                              87
  5611.  
  5612.  
  5613. Function:
  5614.      The VERSION() function returns the version number of dB Online in use.
  5615.  
  5616. Syntax:
  5617.      VERSION()
  5618.  
  5619. Return Value:
  5620.      CHARACTER
  5621.  
  5622. Example:
  5623. ?VERSION()                                         dB Online 1.10
  5624.  
  5625. See Also:
  5626.      DISKSPACE(), GETENV(), OS()
  5627.  
  5628. YEAR()
  5629.  
  5630.  
  5631. Function:
  5632.      The YEAR() function returns  a number representing  the year from  a date
  5633. expression.
  5634.  
  5635. Syntax:
  5636.      YEAR(<dexpr>)
  5637.  
  5638. Return Value:
  5639.      NUMERIC
  5640.  
  5641. Example:
  5642.      Assume the system date is 10/21/93
  5643.  
  5644. ? YEAR(DATE())                                     1993
  5645.  
  5646. See Also:
  5647.      DATE(), DAY(), MONTH()
  5648.  
  5649.  
  5650.  
  5651.  
  5652.  
  5653.  
  5654.  
  5655.  
  5656.  
  5657.  
  5658.  
  5659.  
  5660.  
  5661.  
  5662.  
  5663.  
  5664.  
  5665.  
  5666.  
  5667.  
  5668.  
  5669.  
  5670.  
  5671.  
  5672.  
  5673.                                                                              88
  5674.  
  5675.  
  5676. BBS Information Functions
  5677.  
  5678. The BBS Information Functions  provide a way  to include information  from the
  5679. BBS drop files into a dB Online application.  Included with the description of
  5680. each function is a  Valid With clause.   This determines which BBS  drop files
  5681. provide the information for the given function.  If this  BBS drop file is not
  5682. included in the command line of dB Online a null value will be returned by the
  5683. BBS Information Function.
  5684.  
  5685.  
  5686. BAUD()
  5687.  
  5688. Function:
  5689.      The BAUD() function returns the baud the user connected at.
  5690.  
  5691. Syntax:
  5692.      BAUD()
  5693.  
  5694. Return Value:
  5695.      NUMERIC
  5696.  
  5697. Remarks:
  5698.      If the user is connected locally, then BAUD() returns zero.
  5699.  
  5700. Valid With:
  5701.      pcboard.sys,    exitinfo.bbs,    door.sys,    dorinfox.def,    chain.txt,
  5702. callinfo.bbs
  5703.  
  5704. See Also:
  5705.      COMMPORT(), DTE()
  5706.  
  5707.  
  5708. BBSNAME()
  5709.  
  5710.  
  5711. Function:
  5712.      The BBSNAME() function returns the name of the calling BBS.
  5713.  
  5714. Syntax:
  5715.      BBSNAME()
  5716.  
  5717. Return Value:
  5718.      CHARACTER
  5719.  
  5720.  
  5721. Valid With:
  5722.      chain.txt, dorinfox.def
  5723.  
  5724. CITY()
  5725.  
  5726.  
  5727. Function:
  5728.      The CITY() function returns the user's city and state or province.
  5729.  
  5730. Syntax:
  5731.      CITY()
  5732.  
  5733. Return Value:
  5734.      CHARACTER
  5735.  
  5736.                                                                              89
  5737.  
  5738.  
  5739.  
  5740. Valid With:
  5741.      exitinfo.bbs, door.sys, dorinfo1.def, users.sys, callinfo.bbs
  5742.  
  5743. COMMPORT()
  5744.  
  5745.  
  5746. Function:
  5747.      The COMMPORT() function returns a numeric value corresponding to the comm
  5748.      port connection.
  5749.  
  5750. Syntax:
  5751.      COMMPORT()
  5752.  
  5753. Return Value:
  5754.      NUMERIC
  5755.  
  5756. Remarks:
  5757.      If the user is connected locally, then COMMPORT() will return zero.
  5758.  
  5759. Valid With:
  5760.      pcboard.sys, door.sys, dorinfo1.def, chain.txt, callinfo.bbs
  5761.  
  5762. See Also:
  5763.      BAUD(), DTE(), ISLOCAL()
  5764.  
  5765. CONFERENCE()
  5766.  
  5767.  
  5768. Function:
  5769.      The CONFERENCE() function returns the  number of the   conference or area
  5770.      the user was in before calling the dB Online door.
  5771.  
  5772. Syntax:
  5773.      CONFERENCE()
  5774.  
  5775. Return Value:
  5776.      NUMERIC
  5777.  
  5778. Valid With:
  5779.      pcboard.sys, door.sys
  5780.  
  5781. See Also:
  5782.      NODE()
  5783.  
  5784.  
  5785. DATABITS()
  5786.  
  5787. Function:
  5788.      The DATABITS() function  returns the  number of  databits of  the current
  5789.      communications port.
  5790.  
  5791. Syntax:
  5792.      DATABITS()
  5793.  
  5794. Return Value:
  5795.      NUMERIC
  5796.  
  5797. Valid With:
  5798.  
  5799.                                                                              90
  5800.  
  5801.  
  5802.      dorinfox.def, callinfo.bbs
  5803.  
  5804. Remarks:
  5805.      If a valid BBS drop file does not  exist, the DATABITS() function returns
  5806.      a default value of 8.
  5807.  
  5808. See Also:
  5809.      PARITY(), STOPBITS()
  5810.  
  5811. DATAPHONE()
  5812.  
  5813.  
  5814. Function:
  5815.      The DATAPHONE() function returns the user's data phone number.
  5816.  
  5817. Syntax:
  5818.      DATAPHONE()
  5819.  
  5820. Return Value:
  5821.      NUMERIC
  5822.  
  5823. Valid With:
  5824.      exitinfo.bbs, door.sys, users.sys, callinfo.bbs
  5825.  
  5826. See Also:
  5827.      VOICEPHONE()
  5828.  
  5829. DTE()
  5830.  
  5831.  
  5832. Function:
  5833.      The DTE() function returns the DTE baud of the user.
  5834.  
  5835. Syntax:
  5836.      DTE()
  5837.  
  5838. Return Value:
  5839.      NUMERIC
  5840.  
  5841. Valid With:
  5842.      pcboard.sys, door.sys, callinfo.bbs
  5843.  
  5844. See Also:
  5845.      BAUD(), COMMPORT()
  5846.  
  5847.  
  5848. ERRORCOR()
  5849.  
  5850. Function:
  5851.      The ERRORCOR() function identifies if an  error correcting connection has
  5852.      been established.
  5853.  
  5854. Syntax:
  5855.      ERRORCOR()
  5856.  
  5857. Return Value:
  5858.      LOGICAL
  5859.  
  5860. Valid With:
  5861.  
  5862.                                                                              91
  5863.  
  5864.  
  5865.      pcboard.sys, exitinfo.bbs, door.sys, callinfo.bbs
  5866.  
  5867. FIRSTNAME()
  5868.  
  5869.  
  5870. Function:
  5871.      The FIRSTNAME() function returns  the user's first name  with appropriate
  5872.      capitalization.
  5873.  
  5874. Syntax:
  5875.      FIRSTNAME()
  5876.  
  5877. Return Value:
  5878.      CHARACTER
  5879.  
  5880. Valid With:
  5881.      pcboard.sys, dorinfo1.def
  5882.  
  5883. See Also:
  5884.      USERNAME()
  5885.  
  5886. ISANSI()
  5887.  
  5888.  
  5889. Function:
  5890.      The ISANSI()  function returns  whether the  user is  in ANSI  compatible
  5891.      mode.
  5892.  
  5893. Syntax:
  5894.      ISANSI()
  5895.  
  5896. Return Value:
  5897.      LOGICAL
  5898.  
  5899. Valid With:
  5900.      pcboard.sys, door.sys, dorinfo1.def, chain.txt
  5901.  
  5902. See Also:
  5903.      ISCOLOR(), ISRIP()
  5904.  
  5905.  
  5906. ISCOLOR()
  5907.  
  5908. Function:
  5909.      The ISCOLOR() function returns whether the user is in color mode.
  5910.  
  5911. Syntax:
  5912.      ISCOLOR()
  5913.  
  5914. Return Value:
  5915.      LOGICAL
  5916.  
  5917. Valid With:
  5918.      pcboard.sys, door.sys, callinfo.bbs
  5919.  
  5920. See Also:
  5921.      ISANSI(), ISRIP(), SET COLOR, 
  5922.  
  5923.  
  5924.  
  5925.                                                                              92
  5926.  
  5927.  
  5928. ISLOCAL()
  5929.  
  5930. Function:
  5931.      The ISLOCAL() function returns whether the user is in local mode.
  5932.  
  5933. Syntax:
  5934.      ISLOCAL()
  5935.  
  5936. Return Value:
  5937.      LOGICAL
  5938.  
  5939. Valid With:
  5940.      all
  5941.  
  5942.  
  5943. ISRIP()
  5944.  
  5945. Function:
  5946.      The ISRIP() function returns whether the user is in RIP mode.
  5947.  
  5948. Syntax:
  5949.      ISRIP()
  5950.  
  5951. Return Value:
  5952.      LOGICAL
  5953.  
  5954. Valid With:
  5955.      pcboard.sys, door.sys
  5956.  
  5957. See Also:
  5958.      ISANSI(), ISCOLOR()
  5959.  
  5960.  
  5961. LANGUAGE()
  5962.  
  5963. Function:
  5964.      The LANGUAGE() function returns the user's language filename extension.
  5965.  
  5966. Syntax:
  5967.      LANGUAGE()
  5968.  
  5969. Return Value:
  5970.      CHARACTER
  5971.  
  5972. Valid With:
  5973.      pcboard.sys
  5974.  
  5975. Remarks:
  5976.      The LANGUAGE()  function  will  return  a  null string  if  the  language
  5977.      extension is  English.   Otherwise it  will return  a 4  character string
  5978.      which could correspond to  the extension on  text files to  be displayed:
  5979.      i.e..  If the French language is chosen then ".FRE" is returned.
  5980.  
  5981.  
  5982.  
  5983.  
  5984.  
  5985.  
  5986.  
  5987.  
  5988.                                                                              93
  5989.  
  5990.  
  5991. NODE()
  5992.  
  5993. Function:
  5994.      The NODE() function return the node number the user is on.
  5995.  
  5996. Syntax:
  5997.      NODE()
  5998.  
  5999. Return Value:
  6000.      NUMERIC
  6001.  
  6002. Valid With:
  6003.      pcboard.sys, door.sys, callinfo.bbs
  6004.  
  6005. Remarks:
  6006.      The NODE() function is useful for creating temporary  file names for each
  6007.      BBS node.
  6008.  
  6009. See Also:
  6010.      CONFERENCE()
  6011.  
  6012.  
  6013. PAGELEN()
  6014.  
  6015. Function:
  6016.      The PAGELEN() function returns the user's page length setting.
  6017.  
  6018. Syntax:
  6019.      PAGELEN()
  6020.  
  6021. Return Value: 
  6022.      NUMERIC
  6023.  
  6024. Valid With:
  6025.      exitinfo.bbs, door.sys, user.sys, chain.txt, callinfo.bbs
  6026.  
  6027. See Also:
  6028.      @..SAY...GET
  6029.  
  6030.  
  6031. PARITY()
  6032.  
  6033. Function:
  6034.      The PARITY() function identifies  the parity setting of  the current comm
  6035.      port.
  6036.  
  6037. Syntax:
  6038.      PARITY()
  6039.  
  6040. Return Value: 
  6041.      CHARACTER
  6042.  
  6043. Valid With:
  6044.      door.sys
  6045.  
  6046. Remarks:
  6047.      PARITY() will return 'EVEN' for even parity and 'NONE' for no parity.
  6048.  
  6049.  
  6050.  
  6051.                                                                              94
  6052.  
  6053.  
  6054. PASSWORD()
  6055.  
  6056. Function:
  6057.      The PASSWORD() function returns the user's password.
  6058.  
  6059. Syntax:
  6060.      PASSWORD()
  6061.  
  6062. Return Value:
  6063.      CHARACTER
  6064.  
  6065. Valid With:
  6066.      pcboard.sys, door.sys, users.sys, callinfo.bbs
  6067.  
  6068. See Also:
  6069.      SECURITY()
  6070.  
  6071.  
  6072. PROTOCOL()
  6073.  
  6074. Function:
  6075.      The PROTOCOL() function returns the user's selected protocol.
  6076.  
  6077. Syntax:
  6078.      PROTOCOL()
  6079.  
  6080. Return Value:
  6081.      CHARACTER
  6082.  
  6083. Valid With:
  6084.      door.sys, users.sys, callinfo.bbs
  6085.  
  6086. Remarks: 
  6087.      The return value will be a single character.  Possible values include:
  6088.  
  6089.                       Return Value   Protocol
  6090.  
  6091.                              A       ASCII
  6092.                              X       Xmodem
  6093.  
  6094.                              C       Xmodem-CRC
  6095.                              1       Xmodem-1K
  6096.                              Y       Ymodem (batch)
  6097.  
  6098.                              G       Ymodem-G
  6099.                              Z       Zmodem
  6100.                              K       Kermit
  6101.  
  6102.  
  6103. SECURITY()
  6104.  
  6105.  
  6106. Function:
  6107.      The SECURITY() function returns the user's security level.
  6108.  
  6109. Syntax:
  6110.      SECURITY()
  6111.  
  6112.  
  6113.  
  6114.                                                                              95
  6115.  
  6116.  
  6117. Return Value: 
  6118.      NUMERIC
  6119.  
  6120. Valid With:
  6121.      exitinfo.bbs, door.sys, dorinfox.def, users.sys, chain.txt, callinfo.bbs
  6122.  
  6123. See Also:
  6124.      PASSWORD()
  6125.  
  6126. STOPBITS()
  6127.  
  6128.  
  6129. Function:
  6130.      The STOPBITS() function identifies the number of  stopbits of the current
  6131.      comm port settings.
  6132.  
  6133. Syntax:
  6134.      STOPBITS()
  6135.  
  6136. Return Value:
  6137.      NUMERIC
  6138.  
  6139. Valid With:
  6140.      dorinfox.def
  6141.  
  6142. Remarks:
  6143.      If a valid BBS drop file is not included  then STOPBITS returns a default
  6144.      value of one.
  6145.  
  6146. See Also:
  6147.      DATABITS(), PARITY()
  6148.  
  6149. TIMELEFT()
  6150.  
  6151.  
  6152. Function:
  6153.      The TIMELEFT() function returns the user's time left in minutes.
  6154.  
  6155. Syntax:
  6156.      TIMELEFT()
  6157.  
  6158. Return Value:
  6159.      NUMERIC
  6160.  
  6161. Valid With:
  6162.      pcboard.sys, door.sys, dorinfox.def, chain.txt, callinfo.bbs
  6163.  
  6164. Remarks:
  6165.      A timeout  occurs when  dB  Online has  been  running for  the number  of
  6166.      minutes initially passed by the BBS drop files.  If no BBS drop files are
  6167.      specified (i.e. Local  or Stand Alone  operation), the initial  value for
  6168.      TIMELEFT() is 999 minutes.
  6169.  
  6170. See Also:
  6171.      TIME()
  6172.  
  6173.  
  6174.  
  6175.  
  6176.  
  6177.                                                                              96
  6178.  
  6179.  
  6180. USERNAME()
  6181.  
  6182. Function:
  6183.      The USERNAME() function returns the user's full name.
  6184.  
  6185. Syntax:
  6186.      USERNAME()
  6187.  
  6188. Return Value:
  6189.      CHARACTER
  6190.  
  6191. Valid With:
  6192.      pcboard.sys, exitinfo.bbs, door.sys, dorinfo1.def, users.sys, chain.txt,
  6193.      callinfo.bbs
  6194.  
  6195. Remarks:
  6196.      The USERNAME() function returns the name  as the BBS stores it.   This is
  6197.      usually in full capitals.
  6198.  
  6199. See Also:
  6200.      FIRSTNAME()
  6201.  
  6202.  
  6203. VOICEPHONE()
  6204.  
  6205. Function:
  6206.      The VOICEPHONE() function returns the user's voice phone number.
  6207.  
  6208. Syntax:
  6209.      VOICEPHONE()
  6210.  
  6211. Return Value:
  6212.      CHARACTER
  6213.  
  6214. Valid With:
  6215.      exitinfo.bbs, door.sys, users.sys, callinfo.bbs
  6216.  
  6217. See Also:
  6218.      DATAPHONE()
  6219.  
  6220.  
  6221.  
  6222.  
  6223.  
  6224.  
  6225.  
  6226.  
  6227.  
  6228.  
  6229.  
  6230.  
  6231.  
  6232.  
  6233.  
  6234.  
  6235.  
  6236.  
  6237.  
  6238.  
  6239.  
  6240.                                                                              97
  6241.  
  6242.  
  6243.                                                                     Appendices
  6244.  
  6245.  
  6246.  
  6247.  
  6248. Appendix 1:  Errorlevels
  6249.  
  6250.  
  6251. PROGRAM EXECUTION ERRORS
  6252.  
  6253.  
  6254. The following values are returned to the DOS errorlevel upon termination of dB
  6255. Online.  These errors below  100 are returned when execution  is halted during
  6256. .PRG execution.  The error message will appear on the dB Online exit screen.
  6257.  
  6258.  
  6259.   0..Normal Termination
  6260.  
  6261.      The .PRG application completed execution and terminated correctly.
  6262.  
  6263.   1..Runtime Error
  6264.  
  6265.      A runtime  error  occurred  in  the  .PRG application.    Before  program
  6266.      termination the  source .PRG  filename and  line number  of the  error is
  6267.      indicated to assist the debugging process.  Runtime errors can be trapped
  6268.      with the ON ERROR command.
  6269.  
  6270.  10..Auto Timeout
  6271.  
  6272.      The user  time provided  to dB  Online from  the BBS  info functions  has
  6273.      expired during  program  execution.   dB  Online  terminates and  returns
  6274.      control to the calling application.
  6275.  
  6276.  11..Lost Carrier
  6277.  
  6278.      The carrier was lost during program execution.   dB Online terminates and
  6279.      returns control to the calling application.
  6280.  
  6281.  12..Terminated Escape
  6282.  
  6283.      The user pressed  the      <Esc>        key when  SET ESCAPE  was set  to ON.
  6284.      causes  dB  Online  to  terminate  and  return  control  to  the  calling
  6285.      application.
  6286.  
  6287.  13..Unexpected Runtime
  6288.  
  6289.      An internal error has occurred within  dB Online.  Your .DBX  file may be
  6290.      corrupt.  Re-compile the source .PRG file and then execute dB Online.  If
  6291.      this does not solve the problem please contact Merlin Systems Inc.
  6292.  
  6293.  14..Run Stack Overflow
  6294.  
  6295.      An attempt was made to nest procedure calls too deep.   dB Online is able
  6296.      to nest procedure call  up to 20 levels  deep.  If parameters  are passed
  6297.      with procedure calls then this limit is reduced.   If this error persists
  6298.      please contact Merlin Systems Inc.
  6299.  
  6300.  15..Run Stack Underflow
  6301.  
  6302.  
  6303.                                                                              98
  6304.  
  6305.  
  6306.      An internal error has occurred within  dB Online.  Your .DBX  file may be
  6307.      corrupt.  Re-compile the source .PRG file and then execute dB Online.  If
  6308.      this does not solve the problem please contact Merlin Systems Inc.
  6309.  
  6310.  16..Evaluation Stack Overflow
  6311.  
  6312.      An attempt was  made to  evaluate an  expression too  complex for  the dB
  6313.      Online evaluator.  This can be fixed by  splitting the complex expression
  6314.      onto two command lines.  Please contact Merlin System Inc. if you receive
  6315.      this error.
  6316.  
  6317.  17..Evaluation Stack Underflow
  6318.  
  6319.      An internal error has occurred within  dB Online.  Your .DBX  file may be
  6320.      corrupt.  Re-compile the source .PRG file and then execute dB Online.  If
  6321.      this does not solve the problem please contact Merlin Systems Inc.
  6322.  
  6323. START UP ERRORS
  6324.  
  6325.  
  6326.      The following values are returned to the  DOS errorlevel upon termination
  6327.      of dB Online.   These  errors above  100 are  returned when  execution is
  6328.      halted during setup  prior to  .DBX execution.   This error  message will
  6329.      appear on the DOS screen upon exit.
  6330.  
  6331. 100..Syntax Explanation
  6332.  
  6333.      dB Online was executed without any parameters.  This displays the command
  6334.      line syntax information.
  6335.  
  6336. 101..Cannot Open DBX
  6337.  
  6338.      dB Online could not open the  source .DBX file.  Ensure  that your source
  6339.      .PRG file  is   compiled  and the  resultant  .DBX file's  path is  fully
  6340.      specified in the command line.
  6341.  
  6342. 102..Not a Valid DBX
  6343.  
  6344.      The .DBX file is  not a valid  dB Online file.   Ensure that  your source
  6345.      .PRG file is compiled with the current version of COMPILE.EXE
  6346.  
  6347. 103..Cannot Find USERS.SYS File
  6348.  
  6349.      dB Online cannot find the USERS.SYS file specified on the command line.
  6350.  
  6351. 104..Cannot Find PCBOARD.SYS File
  6352.  
  6353. 105..Cannot Find EXITINFO.BBS File
  6354.  
  6355. 106..Cannot Find DORINFO1.DEV File
  6356.  
  6357. 107..Cannot Find DOOR.SYS File
  6358.  
  6359. 108..Cannot Find CALLINFO.BBS File
  6360.  
  6361. 109..Invalid Command Line Argument
  6362.  
  6363.      An invalid argument was included in the command line.
  6364.  
  6365.  
  6366.                                                                              99
  6367.  
  6368.  
  6369. 110..Corrupted DBONLINE.KEY File
  6370.  
  6371.      The DBONLINE.KEY file has been corrupted.   Copy your backup DBONLINE.KEY
  6372.      file to your  DBONLINE directory.   If  this does  not solve  the problem
  6373.      please contact Merlin Systems.
  6374.  
  6375. 111..Expired Beta KEY File
  6376.  
  6377.      The DBONLINE.KEY file that was issued to the beta testers has expired.
  6378.  
  6379. 112..Unable to Open COMM Port
  6380.  
  6381.      dB Online was unable to open  the comm port that was specified  in one of
  6382.      the BBS information files or in the PORT: command line parameter.
  6383.  
  6384. 113..Port Information Not Specified
  6385.  
  6386.      There was no  port information  specified in any  of the  BBS information
  6387.      files and the  PORT: command line  parameter was  not found.   This error
  6388.      only occurs with the -SA option for Stand Alone operation.
  6389.  
  6390. 114..Stand Alone Interrupt
  6391.  
  6392.      The sysop on  the host pressed    <Esc>      on the  call waiting screen  of the
  6393.      Stand Alone  option.   This  causes  dB Online  to  terminate and  return
  6394.      control back to the calling program.
  6395.  
  6396. 115..Stand Alone Unavailable
  6397.  
  6398.      An attempt was  made to  execute dB  Online with  the Stand  Alone option
  6399.      without having  the PRO  version of  dB  Online.   Please contact  Merlin
  6400.      Systems if you wish to upgrade.
  6401.  
  6402.  
  6403.  
  6404.  
  6405.  
  6406.  
  6407.  
  6408.  
  6409.  
  6410.  
  6411.  
  6412.  
  6413.  
  6414.  
  6415.  
  6416.  
  6417.  
  6418.  
  6419.  
  6420.  
  6421.  
  6422.  
  6423.  
  6424.  
  6425.  
  6426.  
  6427.  
  6428.  
  6429.                                                                             100
  6430.  
  6431.  
  6432. Appendix 2:  Compiler Messages
  6433.  
  6434.  
  6435. Error Messages
  6436.  
  6437. The following is a list of error messages displayed by the compiler
  6438.  
  6439.      Alias name required.
  6440.      Character literal required.
  6441.      Exponent too large.
  6442.      Field identifier required.
  6443.      Illegal number of arguments.
  6444.      Misplaced parameters list.
  6445.      Misplaced set procedure command.
  6446.      Missing endcase.
  6447.      Missing enddo.
  6448.      Missing endif.
  6449.      Not a function.
  6450.      On Error only supports procedure calls.
  6451.      Picture clause expected.
  6452.      Procedure name expected.
  6453.      Procedure redeclaration.
  6454.      Right brace expected.
  6455.      Source line too long.
  6456.      Syntax Error.
  6457.      Too Many errors.
  6458.      Unable to open source file.
  6459.      Unexpected command.
  6460.      Unexpected end of line.
  6461.      Unmatched case statement.
  6462.      Unmatched else statement.
  6463.      Unmatched endcase statement.
  6464.      Unmatched enddo statement.
  6465.      Unmatched endif statement.
  6466.      Unmatched number of parameters.
  6467.      Unmatched otherwise statement.
  6468.      Unmatched variable list.
  6469.      Unrecognized command verb.
  6470.      Variable identifier expected.
  6471.      Work area out of range.
  6472.  
  6473.  
  6474. Warning Messages
  6475.  
  6476.  
  6477. The following is a list of warning messages displayed  by the compiler.  These
  6478. indicate xBase commands that  are not valid  in the dB Online  environment and
  6479. will not affect program execution.
  6480.  
  6481.      CLOSE PROCEDURE ignored
  6482.      SET CATALOG not supported
  6483.      SET DATE not supported
  6484.      SET HEADING not supported
  6485.      SET HELP not supported
  6486.      SET HISTORY not supported
  6487.      SET ODOMETER not supported
  6488.      SET PRINTER not implemented
  6489.      SET PROCEDURE TO ignored
  6490.      SET SAFETY not supported
  6491.  
  6492.                                                                             101
  6493.  
  6494.  
  6495.      SET SCOREBOARD not supported
  6496.      SET STATUS not supported
  6497.      SET TALK not supported
  6498.      TO PRINT not implemented
  6499.  
  6500.  
  6501.  
  6502.  
  6503.  
  6504.  
  6505.  
  6506.  
  6507.  
  6508.  
  6509.  
  6510.  
  6511.  
  6512.  
  6513.  
  6514.  
  6515.  
  6516.  
  6517.  
  6518.  
  6519.  
  6520.  
  6521.  
  6522.  
  6523.  
  6524.  
  6525.  
  6526.  
  6527.  
  6528.  
  6529.  
  6530.  
  6531.  
  6532.  
  6533.  
  6534.  
  6535.  
  6536.  
  6537.  
  6538.  
  6539.  
  6540.  
  6541.  
  6542.  
  6543.  
  6544.  
  6545.  
  6546.  
  6547.  
  6548.  
  6549.  
  6550.  
  6551.  
  6552.  
  6553.  
  6554.  
  6555.                                                                             102
  6556.  
  6557.  
  6558. Appendix 3:  Runtime Errors
  6559.  
  6560. Below is a list  of runtime error  message for dB  Online.  The number  in the
  6561. parenthesis is the value  returned by the   ERROR() function  in error handling
  6562. routines.
  6563.  
  6564.      (24)      ALIAS name already in use:
  6565.      (13)      ALIAS not found:
  6566.      (38)      Beginning of file encountered:
  6567.      (17)      Cannot select requested database:
  6568.      (111)     Cannot write to read-only file:
  6569.      (42)      CONTINUE without LOCATE:
  6570.      (44)      Cyclic relation:
  6571.      (9)       Data type mismatch:
  6572.      (26)      Database is not indexed:
  6573.      (41)      Memo file cannot be opened:
  6574.      (4)       End of file encountered:
  6575.      (77)      Execution error on +: Concatenated string too large:
  6576.      (76)      Execution error on -: Concatenated string too large:
  6577.      (78)      Execution error on ^ or **: Negative base) fractional exponent:
  6578.      (57)      Execution error on CHR(): Out of range:
  6579.      (58)      Execution error on LOG(): Zero or negative:
  6580.      (87)      Execution error on NDX(): Invalid index number:
  6581.      (88)      Execution error on REPLICATE(): String too large:
  6582.      (60)      Execution error on SPACE(): Negative:
  6583.      (59)      Execution error on SPACE(): Too large:
  6584.      (61)      Execution error on SQRT(): Negative:
  6585.      (79)      Execution error on STORE: String too large:
  6586.      (63)      Execution error on STR(): Out of range:
  6587.      (102)     Execution error on STUFF(): String too large:
  6588.      (62)      Execution error on SUBSTR(): Start point out of range:
  6589.      (7)       File already exists:
  6590.      (1)       File does not exist:
  6591.      (3)       File is already open:
  6592.      (108)     File is in use by another:
  6593.      (46)      Illegal value:
  6594.      (19)      Index file does not match database:
  6595.      (106)     Invalid index number:
  6596.      (107)     Invalid operator:
  6597.      (123)     Invalid printer port:
  6598.      (55)      Memory Variable file is invalid:
  6599.      (52)      No database in use:
  6600.      (45)      Not a character expression:
  6601.      (15)      Not a dBASE database:
  6602.      (37)      Not a Logical expression:
  6603.      (27)      Not a numeric expression:
  6604.      (39)      Numeric overflow (data was lost):
  6605.      (90)      Operation with Logical field invalid:
  6606.      (34)      Operation with Memo field invalid:
  6607.      (30)      Position is off the screen:
  6608.      (126)     Printer is either not connected or turned off:
  6609.      (109)     Record is in use by another:
  6610.      (20)      Record is not in index:
  6611.      (5)       Record is out of range:
  6612.      (142)     Relation record is in use by others:
  6613.      (209)     TAG not found:
  6614.      (28)      Too many indices:
  6615.      (92)      Unable to load COMMAND.COM:
  6616.  
  6617.  
  6618.                                                                             103
  6619.  
  6620.  
  6621.      ( 0)      Unable to open file:
  6622.      (12)      Variable not found:
  6623.  
  6624.      (-1)      Shareware version: 50 record max exceeded:
  6625.      (-2)      Multiple work areas not available:
  6626.      (-3)      Shareware version:  Cannot RUN dos commands:
  6627.  
  6628.  
  6629.  
  6630.  
  6631.  
  6632.  
  6633.  
  6634.  
  6635.  
  6636.  
  6637.  
  6638.  
  6639.  
  6640.  
  6641.  
  6642.  
  6643.  
  6644.  
  6645.  
  6646.  
  6647.  
  6648.  
  6649.  
  6650.  
  6651.  
  6652.  
  6653.  
  6654.  
  6655.  
  6656.  
  6657.  
  6658.  
  6659.  
  6660.  
  6661.  
  6662.  
  6663.  
  6664.  
  6665.  
  6666.  
  6667.  
  6668.  
  6669.  
  6670.  
  6671.  
  6672.  
  6673.  
  6674.  
  6675.  
  6676.  
  6677.  
  6678.  
  6679.  
  6680.  
  6681.                                                                             104
  6682.  
  6683.  
  6684. Appendix 4: Full Screen Entry Keys
  6685.  
  6686. The following keys  are used in  full-screen operations.   Keys apply  to both
  6687. data entry screens and the memo editor.
  6688.  
  6689.  
  6690.           Key        Alternative   Function
  6691.           Up         Ctrl-E        Moves the cursor up one line or
  6692.                                    field
  6693.           Down       Ctrl-X        Moves the cursor down one line
  6694.                                    or field
  6695.  
  6696.           Left       Ctrl-S        Moves the cursor one space to
  6697.                                    the left.
  6698.           Right      Ctrl-D        Moves the cursor one space to
  6699.                                    the right.
  6700.           Ctrl-Left  Ctrl-F        Moves the cursor a word left in
  6701.                                    the memo editor
  6702.  
  6703.           Ctrl-Right Ctrl-A        Moves the cursor a word right in
  6704.                                    the memo editor
  6705.           BS         Ctrl-H        Erases the character to the left
  6706.                                    of the cursor
  6707.           Delete     Ctrl-G        Erases the character at the
  6708.                                    current cursor position.
  6709.  
  6710.           End        Ctrl-F        Moves the cursor to the end of
  6711.                                    the line or field
  6712.           Ctrl-End   Ctrl-W        Exits and saves changes to memo
  6713.                                    or entry screens.
  6714.  
  6715.           Enter      Ctrl-M        Moves the cursor to the next
  6716.                                    field or line.
  6717.           Escape     Ctrl-Q        Exits without saving changes.
  6718.           Home       Ctrl-A        Moves the cursor to the start of
  6719.                                    the line or field
  6720.  
  6721.           Insert     Ctrl-V        Toggles insert mode.
  6722.           PgUp       Ctrl-R        Moves the cursor up one page.
  6723.           PgDn       Ctrl-C        Moves the cursor down one page.
  6724.  
  6725.           Ctrl-PgDn  Ctrl-O        Enter full screen memo editor.
  6726.           Ctrl-PgUp  Ctrl-W        Exit memo screen editor.
  6727.           Tab                      Completes field entry and moves
  6728.                                    to next field.
  6729.  
  6730.           Ctrl-Y                   Erases line in memo editor.
  6731.  
  6732.  
  6733.  
  6734.  
  6735.  
  6736.  
  6737.  
  6738.  
  6739.  
  6740.  
  6741.  
  6742.  
  6743.  
  6744.                                                                             105
  6745.  
  6746.  
  6747.  
  6748.           Index
  6749.  
  6750.  
  6751.  
  6752.                                 CTOD(), 61            GO|GOTO, 28
  6753.           ?
  6754.           ?|??, 18              D                     I
  6755.           @...CLEAR, 19         DATABITS(), 90        IF, 29
  6756.           @...SAY...GET, 19     DATAPHONE(), 91       IIF(), 68
  6757.           @...TO, 21            DATE(), 61            IN, 55
  6758.           && (NOTE), 30         DAY(), 62             Index file, 5
  6759.           & (Macro), 57         dBASE III+, 2, 9,     INKEY(), 68
  6760.           * (NOTE), 30          48, 49, 85            INPUT, 29
  6761.                                 dBASE IV, 2, 9, 48,   INT(), 69
  6762.           A                     49, 55, 85            ISALPHA(), 70
  6763.                                 DBF(), 62             ISANSI(), 92
  6764.           ABS(), 57             DBX, 6, 7, 10         ISCOLOR(), 70
  6765.           ACCEPT, 22            DELETE, 25            ISLOCAL(), 93
  6766.           ALIAS, 55             DELETED(), 62         ISLOWER(), 71
  6767.           Aliases, 15, 40       DigiBoard, 13         ISRIP(), 93
  6768.           APPEND BLANK, 22      DISKSPACE(), 63       ISUPPER(), 71
  6769.           Arnet, 13             DISPLAY, 26
  6770.           ASC(), 57             DO, 26                L
  6771.           AT(), 58              DO CASE, 27
  6772.           AVERAGE, 22           DO WHILE, 27          LANGUAGE(), 93
  6773.                                 DOW(), 63             LASTKEY(), 71
  6774.           B                     DTE(), 91             LEFT(), 72
  6775.           BAUD(), 89            DTOC(), 63            LEN(), 72
  6776.           BBS Doorway Mode, 1,                        Licence Levels, 1
  6777.           9                     E                     LIST, 29
  6778.           BBS drop files, 10                          Local/LAN Mode, 1,
  6779.           BBSNAME(), 89         ELSE, 29              10
  6780.           BIOS, 12              ENDCASE, 27           LOCATE, 30
  6781.           BOF(), 58             ENDDO, 27             LOCK(), 73
  6782.                                 ENDIF, 29             LOG(), 73
  6783.           C                     ENDTEXT, 53           LOOP, 27
  6784.           CANCEL, 23            EOF(), 64             LOWER(), 73
  6785.           CASE, 27              ERASE, 28             LTRIM(), 74
  6786.           CDOW(), 59            ERROR(), 65, 103      LUPDATE(), 74
  6787.           CDX, 5, 9, 48         ERRORCOR(), 91
  6788.           CDX(), 59             EXIT, 27              M
  6789.           CHR(), 60             EXP(), 65             MAX(), 74
  6790.           CITY(), 89                                  MDX, 5, 9, 48
  6791.           CLEAR, 23             F                     MDX(), 75
  6792.           CLEAR ALL, 23         FIELD(), 66           MESSAGE(), 75
  6793.           CLEAR GETS, 24        Fields, 4, 15         MIN(), 76
  6794.           CLEAR TYPEAHEAD, 24   FILE(), 66            MOD(), 76
  6795.           Clipper, 2, 9, 48,    FIRSTNAME(), 92       MONTH(), 77
  6796.           49, 85                FLOCK(), 66
  6797.           CLOSE, 24             FOSSIL, 12            N
  6798.           CMONTH(), 60          FOUND(), 67           NDX, 5, 9, 48
  6799.           COL(), 60             FoxPro, 2, 9, 48,     NDX(), 77
  6800.           COM, 12               49, 55, 85            NODE(), 94
  6801.           COMMPORT(), 90                              NOTE, 30
  6802.           CONFERENCE(), 90      G                     NTX, 5, 9, 48
  6803.           CONTINUE, 24          GET, 19
  6804.           COUNT, 25             GETENV(), 68          O
  6805.  
  6806.  
  6807.           Index
  6808.  
  6809.  
  6810.  
  6811.           ON ERROR, 31          SECURITY(), 95        UPPER(), 87
  6812.           ON ESCAPE, 31         SEEK, 39              USE, 55
  6813.           OS(), 77              SELECT, 39            USERNAME(), 97
  6814.           OTHERWISE, 27         SET ALTERNATE, 40
  6815.                                 SET BELL, 41          V
  6816.           P                     SET CENTURY, 41       VAL(), 87
  6817.           PACK, 32              SET COLOR, 41         Variables, 15
  6818.           PAGELEN(), 94         SET CONFIRM, 43       VERSION(), 87
  6819.           PARAMETERS, 32, 33    SET CONSOLE, 43       VOICEPHONE(), 97
  6820.           PARITY(), 94          SET DECIMALS, 43
  6821.           PASSWORD(), 95        SET DEFAULT, 44       W
  6822.           PICTURE, 20           SET DELETED, 44
  6823.           PORT, 10, 12          SET DELIMITERS, 45    WAIT, 55
  6824.           PRG, 6                SET ESCAPE, 45
  6825.           PRIVATE, 33           SET EXACT, 46         Y
  6826.           Pro Version, 1, 38,   SET EXCLUSIVE, 46     YEAR(), 88
  6827.           39, 51                SET FILTER, 46
  6828.           PROCEDURE, 33         SET FIXED, 47
  6829.           PROTOCOL(), 95        SET INDEX, 48
  6830.           PUBLIC, 34            SET INTENSITY, 48
  6831.                                 SET LOCK, 49
  6832.           Q                     SET MEMOWIDTH, 49
  6833.                                 SET ORDER, 49
  6834.           QUIT, 34              SET PATH, 50
  6835.                                 SET PROCEDURE, 50
  6836.           R                     SET PROCEDURE TO, 6
  6837.           RANGE, 19             SET RELATION, 51
  6838.           READ, 34              SET REPROCESS, 51
  6839.           READKEY(), 78         Shareware Version, 1
  6840.           RECALL, 35            SKIP, 52
  6841.           RECCOUNT(), 79        SPACE(), 83
  6842.           RECNO(), 79           SQRT(), 83
  6843.           Record, 4             Stand Alone Mode, 1,
  6844.           RECSIZE(), 80         10
  6845.           Registered Version,   StarGate, 13
  6846.           1, 2, 38              STOPBITS(), 96
  6847.           REINDEX, 35           STORE, 52
  6848.           RENAME, 35            STR(), 84
  6849.           REPLACE, 36           STUFF(), 84
  6850.           REPLICATE(), 80       SUBSTR(), 85
  6851.           RESTORE, 36           SUM, 53
  6852.           RETRY, 37
  6853.           RETURN, 37            T
  6854.           RIGHT(), 81           Tag, 4
  6855.           RLOCK(), 81           TAG(), 85
  6856.           ROUND(), 82           TEXT, 53
  6857.           ROW(), 82             TIME(), 86
  6858.           RTRIM(), 82           TIMELEFT(), 96
  6859.           RUN, 1, 38            TRANSFORM(), 86
  6860.                                 TRIM(), 86
  6861.           S
  6862.           SAVE, 38              U
  6863.           SAY, 19
  6864.                                 UNLOCK, 54
  6865.